Authentication API


Authentication related API end-points for Taskcluster and related services. These API end-points are of interest if you wish to:

  • Authorize a request signed with Taskcluster credentials,
  • Manage clients and roles,
  • Inspect or audit clients and roles,
  • Gain access to various services guarded by this API.

Note that in this service "authentication" refers to validating the correctness of the supplied credentials (that the caller posesses the appropriate access token). This service does not provide any kind of user authentication (identifying a particular person).


The authentication service manages clients, at a high-level each client consists of a clientId, an accessToken, scopes, and some metadata. The clientId and accessToken can be used for authentication when calling Taskcluster APIs.

The client's scopes control the client's access to Taskcluster resources. The scopes are expanded by substituting roles, as defined below.


A role consists of a roleId, a set of scopes and a description. Each role constitutes a simple expansion rule that says if you have the scope: assume:<roleId> you get the set of scopes the role has. Think of the assume:<roleId> as a scope that allows a client to assume a role.

As in scopes the * kleene star also have special meaning if it is located at the end of a roleId. If you have a role with the following roleId: my-prefix*, then any client which has a scope staring with assume:my-prefix will be allowed to assume the role.

Guarded Services

The authentication service also has API end-points for delegating access to some guarded service such as AWS S3, or Azure Table Storage. Generally, we add API end-points to this server when we wish to use Taskcluster credentials to grant access to a third-party service used by many Taskcluster components.

Auth Client

// Create Auth client instance with default baseUrl:

const auth = new taskcluster.Auth(options);

Methods in Auth Client

// auth.listClients :: [options] -> Promise Result
// auth.client :: clientId -> Promise Result
// auth.createClient :: (clientId -> payload) -> Promise Result
auth.createClient(clientId, payload)
// auth.resetAccessToken :: clientId -> Promise Result
// auth.updateClient :: (clientId -> payload) -> Promise Result
auth.updateClient(clientId, payload)
// auth.enableClient :: clientId -> Promise Result
// auth.disableClient :: clientId -> Promise Result
// auth.deleteClient :: clientId -> Promise Nothing
// auth.listRoles :: () -> Promise Result
// auth.role :: roleId -> Promise Result
// auth.createRole :: (roleId -> payload) -> Promise Result
auth.createRole(roleId, payload)
// auth.updateRole :: (roleId -> payload) -> Promise Result
auth.updateRole(roleId, payload)
// auth.deleteRole :: roleId -> Promise Nothing
// auth.expandScopes :: payload -> Promise Result
// auth.currentScopes :: () -> Promise Result
// auth.awsS3Credentials :: (level -> bucket -> prefix -> [options]) -> Promise Result
auth.awsS3Credentials(level, bucket, prefix)
auth.awsS3Credentials(level, bucket, prefix, options)
// auth.azureAccounts :: () -> Promise Result
// auth.azureTables :: (account -> [options]) -> Promise Result
auth.azureTables(account, options)
// auth.azureTableSAS :: (account -> table -> level) -> Promise Result
auth.azureTableSAS(account, table, level)
// auth.azureBlobSAS :: (account -> container -> level) -> Promise Result
auth.azureBlobSAS(account, container, level)
// auth.sentryDSN :: project -> Promise Result
// auth.statsumToken :: project -> Promise Result
// auth.webhooktunnelToken :: () -> Promise Result
// auth.authenticateHawk :: payload -> Promise Result
// auth.testAuthenticate :: payload -> Promise Result
// auth.testAuthenticateGet :: () -> Promise Result
// :: () -> Promise Nothing