Authentication API


BaseUrl
https://auth.taskcluster.net/v1

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).

Clients

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.

Roles

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.

Functions

For more information on invoking the API methods described here, see Using the APIs in the manual.
SignatureSummary
listClients({prefix}) : resultList Clients
client(clientId) : resultGet Client
createClient(clientId, payload) : resultCreate Client
resetAccessToken(clientId) : resultReset `accessToken`
updateClient(clientId, payload) : resultUpdate Client
enableClient(clientId) : resultEnable Client
disableClient(clientId) : resultDisable Client
deleteClient(clientId) : voidDelete Client
listRoles() : resultList Roles
role(roleId) : resultGet Role
createRole(roleId, payload) : resultCreate Role
updateRole(roleId, payload) : resultUpdate Role
deleteRole(roleId) : voidDelete Role
expandScopes(payload) : resultExpand Scopes
currentScopes() : resultGet Current Scopes
awsS3Credentials(level, bucket, prefix, {format}) : resultGet Temporary Read/Write Credentials S3
azureAccounts() : resultList Accounts Managed by Auth
azureTables(account, {continuationToken}) : resultList Tables in an Account Managed by Auth
azureTableSAS(account, table, level) : resultGet Shared-Access-Signature for Azure Table
azureBlobSAS(account, container, level) : resultGet Shared-Access-Signature for Azure Blob
sentryDSN(project) : resultGet DSN for Sentry Project
statsumToken(project) : resultGet Token for Statsum Project
webhooktunnelToken() : resultGet Token for Webhooktunnel Proxy
authenticateHawk(payload) : resultAuthenticate Hawk Request
testAuthenticate(payload) : resultTest Authentication
testAuthenticateGet() : resultTest Authentication (GET)
ping() : voidPing Server

List Clients

Method
get
Route
/clients/
Signature
listClients({prefix}) : result
Stability
stable

Get a list of all clients. With prefix, only clients for which it is a prefix of the clientId are returned.

Response

List Client Response (source)

List of clients

Array of

List of clients

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId of the client scopes is requested about

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false, the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this client was created

lastModifiedstringdate-time

Date and time of last modification

lastDateUsedstringdate-time

Date of last time this client was used. Will only be updated every 6 hours or so this may be off by up-to 6 hours. But it still gives a solid hint as to whether or not this client is in use.

lastRotatedstringdate-time

Date and time of when the accessToken was reset last time.

scopesArray of
default:

List of scopes the client has (unexpanded). Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

expandedScopesArray of

List of scopes granted to this client by matching roles. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope that client is granted by a role

disabledboolean

If true, this client is disabled and cannot be used. This usually occurs when the scopes available to the user owning the client no longer satisfy the client.



Get Client

Method
get
Route
/clients/<clientId>
Signature
client(clientId) : result
Stability
stable

Get information about a single client.

Response

Get Client Response (source)

Get all details about a client, useful for tools modifying a client

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId of the client scopes is requested about

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false, the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this client was created

lastModifiedstringdate-time

Date and time of last modification

lastDateUsedstringdate-time

Date of last time this client was used. Will only be updated every 6 hours or so this may be off by up-to 6 hours. But it still gives a solid hint as to whether or not this client is in use.

lastRotatedstringdate-time

Date and time of when the accessToken was reset last time.

scopesArray of
default:

List of scopes the client has (unexpanded). Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

expandedScopesArray of

List of scopes granted to this client by matching roles. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope that client is granted by a role

disabledboolean

If true, this client is disabled and cannot be used. This usually occurs when the scopes available to the user owning the client no longer satisfy the client.



Create Client

Method
put
Route
/clients/<clientId>
Scopes
auth:create-client:<clientId>
Signature
createClient(clientId, payload) : result
Stability
stable

Create a new client and get the accessToken for this client. You should store the accessToken from this API call as there is no other way to retrieve it.

If you loose the accessToken you can call resetAccessToken to reset it, and a new accessToken will be returned, but you cannot retrieve the current accessToken.

If a client with the same clientId already exists this operation will fail. Use updateClient if you wish to update an existing client.

The caller's scopes must satisfy scopes.

Request Payload

Create Client Request (source)

Properties to create a client.

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false (the default), the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

scopesArray of

List of scopes the client has. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

Response

Create Client Response (source)

All details about a client including the accessToken

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId of the client

accessTokenstring^[a-zA-Z0-9_-]{22,66}$

AccessToken used for authenticating requests, you should store this you won't be able to retrive it again!

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false, the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this client was created

lastModifiedstringdate-time

Date and time of last modification

lastDateUsedstringdate-time

Date of last time this client was used. Will only be updated every 6 hours or so this may be off by up-to 6 hours. But it still gives a solid hint as to whether or not this client is in use.

lastRotatedstringdate-time

Date and time of when the accessToken was reset last time.

scopesArray of
default:

List of scopes the client has (unexpanded). Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

expandedScopesArray of

List of scopes granted to this client by matching roles, including the client's scopes and the implicit role client-id:<clientId>.

string^[ -~]*$

Scope that client is granted

disabledboolean

If true, this client is disabled and cannot be used. This usually occurs when the scopes available to the user owning the client no longer satisfy the client.



Reset accessToken

Method
post
Route
/clients/<clientId>/reset
Scopes
auth:reset-access-token:<clientId>
Signature
resetAccessToken(clientId) : result
Stability
stable

Reset a clients accessToken, this will revoke the existing accessToken, generate a new accessToken and return it from this call.

There is no way to retrieve an existing accessToken, so if you loose it you must reset the accessToken to acquire it again.

Response

Create Client Response (source)

All details about a client including the accessToken

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId of the client

accessTokenstring^[a-zA-Z0-9_-]{22,66}$

AccessToken used for authenticating requests, you should store this you won't be able to retrive it again!

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false, the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this client was created

lastModifiedstringdate-time

Date and time of last modification

lastDateUsedstringdate-time

Date of last time this client was used. Will only be updated every 6 hours or so this may be off by up-to 6 hours. But it still gives a solid hint as to whether or not this client is in use.

lastRotatedstringdate-time

Date and time of when the accessToken was reset last time.

scopesArray of
default:

List of scopes the client has (unexpanded). Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

expandedScopesArray of

List of scopes granted to this client by matching roles, including the client's scopes and the implicit role client-id:<clientId>.

string^[ -~]*$

Scope that client is granted

disabledboolean

If true, this client is disabled and cannot be used. This usually occurs when the scopes available to the user owning the client no longer satisfy the client.



Update Client

Method
post
Route
/clients/<clientId>
Scopes
auth:update-client:<clientId>
Signature
updateClient(clientId, payload) : result
Stability
stable

Update an exisiting client. The clientId and accessToken cannot be updated, but scopes can be modified. The caller's scopes must satisfy all scopes being added to the client in the update operation. If no scopes are given in the request, the client's scopes remain unchanged

Request Payload

Create Client Request (source)

Properties to create a client.

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false (the default), the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

scopesArray of

List of scopes the client has. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

Response

Get Client Response (source)

Get all details about a client, useful for tools modifying a client

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId of the client scopes is requested about

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false, the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this client was created

lastModifiedstringdate-time

Date and time of last modification

lastDateUsedstringdate-time

Date of last time this client was used. Will only be updated every 6 hours or so this may be off by up-to 6 hours. But it still gives a solid hint as to whether or not this client is in use.

lastRotatedstringdate-time

Date and time of when the accessToken was reset last time.

scopesArray of
default:

List of scopes the client has (unexpanded). Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

expandedScopesArray of

List of scopes granted to this client by matching roles. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope that client is granted by a role

disabledboolean

If true, this client is disabled and cannot be used. This usually occurs when the scopes available to the user owning the client no longer satisfy the client.



Enable Client

Method
post
Route
/clients/<clientId>/enable
Scopes
auth:enable-client:<clientId>
Signature
enableClient(clientId) : result
Stability
stable

Enable a client that was disabled with disableClient. If the client is already enabled, this does nothing.

This is typically used by identity providers to re-enable clients that had been disabled when the corresponding identity's scopes changed.

Response

Get Client Response (source)

Get all details about a client, useful for tools modifying a client

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId of the client scopes is requested about

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false, the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this client was created

lastModifiedstringdate-time

Date and time of last modification

lastDateUsedstringdate-time

Date of last time this client was used. Will only be updated every 6 hours or so this may be off by up-to 6 hours. But it still gives a solid hint as to whether or not this client is in use.

lastRotatedstringdate-time

Date and time of when the accessToken was reset last time.

scopesArray of
default:

List of scopes the client has (unexpanded). Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

expandedScopesArray of

List of scopes granted to this client by matching roles. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope that client is granted by a role

disabledboolean

If true, this client is disabled and cannot be used. This usually occurs when the scopes available to the user owning the client no longer satisfy the client.



Disable Client

Method
post
Route
/clients/<clientId>/disable
Scopes
auth:disable-client:<clientId>
Signature
disableClient(clientId) : result
Stability
stable

Disable a client. If the client is already disabled, this does nothing.

This is typically used by identity providers to disable clients when the corresponding identity's scopes no longer satisfy the client's scopes.

Response

Get Client Response (source)

Get all details about a client, useful for tools modifying a client

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId of the client scopes is requested about

expiresstringdate-time

Date and time where the clients access is set to expire

deleteOnExpirationboolean

If true, the service may delete this client after it has expired. If false, the client will remain after expiration, although it cannot be used for authentication in that state.

descriptionstring[0:10240]

Description of what these credentials are used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this client was created

lastModifiedstringdate-time

Date and time of last modification

lastDateUsedstringdate-time

Date of last time this client was used. Will only be updated every 6 hours or so this may be off by up-to 6 hours. But it still gives a solid hint as to whether or not this client is in use.

lastRotatedstringdate-time

Date and time of when the accessToken was reset last time.

scopesArray of
default:

List of scopes the client has (unexpanded). Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

expandedScopesArray of

List of scopes granted to this client by matching roles. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope that client is granted by a role

disabledboolean

If true, this client is disabled and cannot be used. This usually occurs when the scopes available to the user owning the client no longer satisfy the client.



Delete Client

Method
delete
Route
/clients/<clientId>
Scopes
auth:delete-client:<clientId>
Signature
deleteClient(clientId) : void
Stability
stable

Delete a client, please note that any roles related to this client must be deleted independently.



List Roles

Method
get
Route
/roles/
Signature
listRoles() : result
Stability
stable

Get a list of all roles, each role object also includes the list of scopes it expands to.

Response

List Roles Response (source)

List of roles

Array of

List of roles

roleIdstring^[\x20-\x7e]+$

roleId of the role requested

scopesArray of

List of scopes the role grants access to. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope the role grants access to

descriptionstring[0:10240]

Description of what this role is used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this role was created

lastModifiedstringdate-time

Date and time of last modification

expandedScopesArray of

List of scopes granted anyone who assumes this role, including anything granted by roles that can be assumed when you have this role. Hence, this includes any scopes in-directly granted as well.

string^[ -~]*$

Scope this role grants



Get Role

Method
get
Route
/roles/<roleId>
Signature
role(roleId) : result
Stability
stable

Get information about a single role, including the set of scopes that the role expands to.

Response

Get Role Response (source)

Get all details about a role

roleIdstring^[\x20-\x7e]+$

roleId of the role requested

scopesArray of

List of scopes the role grants access to. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope the role grants access to

descriptionstring[0:10240]

Description of what this role is used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this role was created

lastModifiedstringdate-time

Date and time of last modification

expandedScopesArray of

List of scopes granted anyone who assumes this role, including anything granted by roles that can be assumed when you have this role. Hence, this includes any scopes in-directly granted as well.

string^[ -~]*$

Scope this role grants



Create Role

Method
put
Route
/roles/<roleId>
Scopes
auth:create-role:<roleId>
Signature
createRole(roleId, payload) : result
Stability
stable

Create a new role.

The caller's scopes must satisfy the new role's scopes.

If there already exists a role with the same roleId this operation will fail. Use updateRole to modify an existing role.

Request Payload

Create Role Request (source)

Data to create or update a role.

scopesArray of

List of scopes the role grants access to. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope the role grants access to

descriptionstring[0:10240]

Description of what this role is used for in markdown. Should include who is the owner, point of contact.

Response

Get Role Response (source)

Get all details about a role

roleIdstring^[\x20-\x7e]+$

roleId of the role requested

scopesArray of

List of scopes the role grants access to. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope the role grants access to

descriptionstring[0:10240]

Description of what this role is used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this role was created

lastModifiedstringdate-time

Date and time of last modification

expandedScopesArray of

List of scopes granted anyone who assumes this role, including anything granted by roles that can be assumed when you have this role. Hence, this includes any scopes in-directly granted as well.

string^[ -~]*$

Scope this role grants



Update Role

Method
post
Route
/roles/<roleId>
Scopes
auth:update-role:<roleId>
Signature
updateRole(roleId, payload) : result
Stability
stable

Update an existing role.

The caller's scopes must satisfy all of the new scopes being added, but need not satisfy all of the client's existing scopes.

Request Payload

Create Role Request (source)

Data to create or update a role.

scopesArray of

List of scopes the role grants access to. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope the role grants access to

descriptionstring[0:10240]

Description of what this role is used for in markdown. Should include who is the owner, point of contact.

Response

Get Role Response (source)

Get all details about a role

roleIdstring^[\x20-\x7e]+$

roleId of the role requested

scopesArray of

List of scopes the role grants access to. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope the role grants access to

descriptionstring[0:10240]

Description of what this role is used for in markdown. Should include who is the owner, point of contact.

createdstringdate-time

Date and time when this role was created

lastModifiedstringdate-time

Date and time of last modification

expandedScopesArray of

List of scopes granted anyone who assumes this role, including anything granted by roles that can be assumed when you have this role. Hence, this includes any scopes in-directly granted as well.

string^[ -~]*$

Scope this role grants



Delete Role

Method
delete
Route
/roles/<roleId>
Scopes
auth:delete-role:<roleId>
Signature
deleteRole(roleId) : void
Stability
stable

Delete a role. This operation will succeed regardless of whether or not the role exists.



Expand Scopes

Method
get
Route
/scopes/expand
Signature
expandScopes(payload) : result
Stability
stable

Return an expanded copy of the given scopeset, with scopes implied by any roles included.

Request Payload

Set of scopes (source)

A set of scopes

scopesArray of

List of scopes. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope

Response

Set of scopes (source)

A set of scopes

scopesArray of

List of scopes. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope



Get Current Scopes

Method
get
Route
/scopes/current
Signature
currentScopes() : result
Stability
stable

Return the expanded scopes available in the request, taking into account all sources of scopes and scope restrictions (temporary credentials, assumeScopes, client scopes, and roles).

Response

Set of scopes (source)

A set of scopes

scopesArray of

List of scopes. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$

Scope



Get Temporary Read/Write Credentials S3

Method
get
Route
/aws/s3/<level>/<bucket>/<prefix>
Scopes
auth:aws-s3:<level>:<bucket>/<prefix>
Signature
awsS3Credentials(level, bucket, prefix, {format}) : result
Stability
stable

Get temporary AWS credentials for read-write or read-only access to a given bucket and prefix within that bucket. The level parameter can be read-write or read-only and determines which type of credentials are returned. Please note that the level parameter is required in the scope guarding access. The bucket name must not contain ., as recommended by Amazon.

This method can only allow access to a whitelisted set of buckets. To add a bucket to that whitelist, contact the Taskcluster team, who will add it to the appropriate IAM policy. If the bucket is in a different AWS account, you will also need to add a bucket policy allowing access from the Taskcluster account. That policy should look like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "allow-taskcluster-auth-to-delegate-access",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::692406183521:root"
      },
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket>",
        "arn:aws:s3:::<bucket>/*"
      ]
    }
  ]
}

The credentials are set to expire after an hour, but this behavior is subject to change. Hence, you should always read the expires property from the response, if you intend to maintain active credentials in your application.

Please note that your prefix may not start with slash /. Such a prefix is allowed on S3, but we forbid it here to discourage bad behavior.

Also note that if your prefix doesn't end in a slash /, the STS credentials may allow access to unexpected keys, as S3 does not treat slashes specially. For example, a prefix of my-folder will allow access to my-folder/file.txt as expected, but also to my-folder.txt, which may not be intended.

Finally, note that the PutObjectAcl call is not allowed. Passing a canned ACL other than private to PutObject is treated as a PutObjectAcl call, and will result in an access-denied error from AWS. This limitation is due to a security flaw in Amazon S3 which might otherwise allow indefinite access to uploaded objects.

EC2 metadata compatibility, if the querystring parameter ?format=iam-role-compat is given, the response will be compatible with the JSON exposed by the EC2 metadata service. This aims to ease compatibility for libraries and tools built to auto-refresh credentials. For details on the format returned by EC2 metadata service see: EC2 User Guide.

Response

AWS S3 Credentials Response (source)

Response for a request to get access to an S3 bucket.

credentialsObject of

Response for a request to get access to an S3 bucket.

accessKeyIdstring

Access key identifier that identifies the temporary security credentials.

secretAccessKeystring

Secret access key used to sign requests

sessionTokenstring

A token that must passed with request to use the temporary security credentials.

expiresstringdate-time

Date and time of when the temporary credentials expires.



List Accounts Managed by Auth

Method
get
Route
/azure/accounts
Scopes
auth:azure-table:list-accounts
Signature
azureAccounts() : result
Stability
stable

Retrieve a list of all Azure accounts managed by Taskcluster Auth.

Response

Azure List Account Response (source)

A list of Azure accounts managed by taskcluster-auth

accountsArray of

A list of accountIds that are managed by auth. These are the accounts that can have SAS credentials fetched for tables within them.

string


List Tables in an Account Managed by Auth

Method
get
Route
/azure/<account>/tables
Scopes
auth:azure-table:list-tables:<account>
Signature
azureTables(account, {continuationToken}) : result
Stability
stable

Retrieve a list of all tables in an account.

Response

Azure List Account Response (source)

A list of Azure tables in an account

tablesArray of

A list of tables that are in an account. These are the tables that can have SAS credentials fetched for them.

string
continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of tables. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called azureAccountTables with continuationToken until you get a result without a continuationToken.



Get Shared-Access-Signature for Azure Table

Method
get
Route
/azure/<account>/table/<table>/<level>
Scopes
auth:azure-table:<level>:<account>/<table>
Signature
azureTableSAS(account, table, level) : result
Stability
stable

Get a shared access signature (SAS) string for use with a specific Azure Table Storage table.

The level parameter can be read-write or read-only and determines which type of credentials are returned. If level is read-write, it will create the table if it doesn't already exist.

Response

Azure Table Shared-Access-Signature Response (source)

Response to a request for an Shared-Access-Signature to access and Azure Table Storage table.

sasstring

Shared-Access-Signature string. This is the querystring parameters to be appened after ? or & depending on whether or not a querystring is already present in the URL.

expirystringdate-time

Date and time of when the Shared-Access-Signature expires.



Get Shared-Access-Signature for Azure Blob

Method
get
Route
/azure/<account>/containers/<container>/<level>
Scopes
auth:azure-blob:<level>:<account>/<container>
Signature
azureBlobSAS(account, container, level) : result
Stability
stable

Get a shared access signature (SAS) string for use with a specific Azure Blob Storage container.

The level parameter can be read-write or read-only and determines which type of credentials are returned. If level is read-write, it will create the container if it doesn't already exist.

Response

Azure Blob Shared-Access-Signature Response (source)

Response to a request for an Shared-Access-Signature to access an Azure Blob Storage container.

sasstring

Shared-Access-Signature string. This is the querystring parameters to be appened after ? or & depending on whether or not a querystring is already present in the URL.

expirystringdate-time

Date and time of when the Shared-Access-Signature expires.



Get DSN for Sentry Project

Method
get
Route
/sentry/<project>/dsn
Scopes
auth:sentry:<project>
Signature
sentryDSN(project) : result
Stability
stable

Get temporary DSN (access credentials) for a sentry project. The credentials returned can be used with any Sentry client for up to 24 hours, after which the credentials will be automatically disabled.

If the project doesn't exist it will be created, and assigned to the initial team configured for this component. Contact a Sentry admin to have the project transferred to a team you have access to if needed

Response

Sentry DSN Response (source)

Sentry DSN for submitting errors.

projectstring

Project name that the DSN grants access to.

dsnObject of

Sentry DSN for submitting errors.

secretstringuri

Access credential and URL for private error reports. These credentials can be used for up-to 24 hours. This is for use in serser-side applications and should not be leaked.

publicstringuri

Access credential and URL for public error reports. These credentials can be used for up-to 24 hours. This is for use in client-side applications only.

expiresstringdate-time

Expiration time for the credentials. The credentials should not be used after this time. They might not be revoked immediately, but will be at some arbitrary point after this date-time.



Get Token for Statsum Project

Method
get
Route
/statsum/<project>/token
Scopes
auth:statsum:<project>
Signature
statsumToken(project) : result
Stability
stable

Get temporary token and baseUrl for sending metrics to statsum.

The token is valid for 24 hours, clients should refresh after expiration.

Response

Statsum Token Response (source)

Token for submitting statistics to statsum.

projectstring

Project name that the token grants access to.

tokenstring

JWT token to be used as Bearer <token> when submitting data to statsum.

expiresstringdate-time

Time at which the token expires and should not be used anymore.

baseUrlstringuri

Base URL for the statsum server this project is allocated on.



Get Token for Webhooktunnel Proxy

Method
get
Route
/webhooktunnel
Scopes
auth:webhooktunnel
Signature
webhooktunnelToken() : result
Stability
stable

Get temporary token and id for connecting to webhooktunnel The token is valid for 96 hours, clients should refresh after expiration.

Response

Webhooktunnel Token Response (source)

Token for connecting a worker to webhooktunnel proxy

tunnelIdstring

id for proxy connection

tokenstring

jwt token to be used as Bearer <token> when connecting to proxy.

proxyUrlstring

websocket url at which proxy is hosted



Authenticate Hawk Request

Method
post
Route
/authenticate-hawk
Signature
authenticateHawk(payload) : result
Stability
stable

Validate the request signature given on input and return list of scopes that the authenticating client has.

This method is used by other services that wish rely on Taskcluster credentials for authentication. This way we can use Hawk without having the secret credentials leave this service.

Request Payload

Hawk Signature Authentication Request (source)

Request to authenticate a hawk request.

methodstring
  • get
  • post
  • put
  • head
  • delete
  • options
  • trace
  • copy
  • lock
  • mkcol
  • move
  • purge
  • propfind
  • proppatch
  • unlock
  • report
  • mkactivity
  • checkout
  • merge
  • m-search
  • notify
  • subscribe
  • unsubscribe
  • patch
  • search
  • connect

HTTP method of the request being authenticated.

resourcestring

Resource the request operates on including querystring. This is the string that follows the HTTP method. Note, order of querystring elements is important.

hostAny of

Host for which the request came in, this is typically the Host header excluding the port if any.

stringhostname
stringipv4
portinteger[0:65535]

Port on which the request came in, this is typically 80 or 443. If you are running behind a reverse proxy look for the x-forwarded-port header.

authorizationstring

Authorization header, must only be specified if request being authenticated has a Authorization header.

Response

Hawk Signature Authentication Response (source)

Response from a request to authenticate a hawk request.

Hawk Signature Authentication ResponseAny of

Response from a request to authenticate a hawk request.

Hawk Signature Authentication ResponseObject of
statusstring
  • auth-success

The kind of response, auth-failed or auth-success.

scopesArray of

List of scopes the client is authorized to access. Scopes must be composed of printable ASCII characters and spaces.

string^[ -~]*$
schemestring
  • hawk

Authentication scheme the client used. Generally, you don't need to read this property unless hash is provided and you want to validate the payload hash. Additional values may be added in the future.

hash

Payload as extracted from Authentication header. This property is only present if a hash is available. You are not required to validate this hash, but if you do, please check scheme to ensure that it's on a scheme you support.

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

The clientId that made this request. This may be the id supplied in the Authorization header, or in the case of a named temporary credential may be embedded in the payload. In any case, this clientId can be used for logging, auditing, and identifying the credential but must not be used for access control. That's what scopes are for.

expiresstringdate-time

The expiration time for the credentials used to make this request. This should be treated as the latest time at which the authorization is valid. For most cases, where the access being authorized occurs immediately, this field can be ignored, as the value will always be in the future if the status is auth-success.

Hawk Signature Authentication ResponseObject of
statusstring
  • auth-failed

The kind of response, auth-failed or auth-success.

messagestring

Message saying why the authentication failed.



Test Authentication

Method
post
Route
/test-authenticate
Signature
testAuthenticate(payload) : result
Stability
stable

Utility method to test client implementations of Taskcluster authentication.

Rather than using real credentials, this endpoint accepts requests with clientId tester and accessToken no-secret. That client's scopes are based on clientScopes in the request body.

The request is validated, with any certificate, authorizedScopes, etc. applied, and the resulting scopes are checked against requiredScopes from the request body. On success, the response contains the clientId and scopes as seen by the API method.

Request Payload

Test Authenticate Request (source)

Details on how the test request should be authenticated.

clientScopesArray of
default:

List of scopes that should be client used should be given.

string^[ -~]*$

Scope

requiredScopesArray of
default:

List of scopes the request should require.

string^[ -~]*$

Scope

Response

Test Authenticate Response (source)

Details on how the test request was authenticated.

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId from the request as it will be logged

scopesArray of
default:

List of scopes the request was authorized.

string^[ -~]*$

Scope



Test Authentication (GET)

Method
get
Route
/test-authenticate-get/
Signature
testAuthenticateGet() : result
Stability
stable

Utility method similar to testAuthenticate, but with the GET method, so it can be used with signed URLs (bewits).

Rather than using real credentials, this endpoint accepts requests with clientId tester and accessToken no-secret. That client's scopes are ['test:*', 'auth:create-client:test:*']. The call fails if the test:authenticate-get scope is not available.

The request is validated, with any certificate, authorizedScopes, etc. applied, and the resulting scopes are checked, just like any API call. On success, the response contains the clientId and scopes as seen by the API method.

This method may later be extended to allow specification of client and required scopes via query arguments.

Response

Test Authenticate Response (source)

Details on how the test request was authenticated.

clientIdstring^[A-Za-z0-9@/:.+|_-]+$

ClientId from the request as it will be logged

scopesArray of
default:

List of scopes the request was authorized.

string^[ -~]*$

Scope



Ping Server

Method
get
Route
/ping
Signature
ping() : void
Stability
stable

Respond without doing anything. This endpoint is used to check that the service is up.