7.2.1.16. Api Tokens API

Endpoints

GET	/api/users/{user}/tokens	Query the tokens of `{user}`
POST	/api/users/{user}/tokens	Create a new API Token
DELETE	/api/tokens	Bulk-delete API Tokens
GET	/api/tokens/{id}	Get Info about an API Token
DELETE	/api/tokens/{id}	Delete an existing API Token

GET /api/users/{user}/tokens

Query the tokens of `{user}`.

Since: 7.1.0

In the Python API this functionality is provided by axivion.dashboard.Dashboard.get_api_tokens().

Status Codes:

• 200 OK –

  Body Type: Array of ApiTokenInfo

  Successful response

POST /api/users/{user}/tokens

Create a new API Token.

Since: 7.1.0

Creates a new API token on the server for {user} and returns Token MetaData as well as the secret needed to use the Token for authentication. This secret cannot be retrieved by other means than consumption of the response to this request.

The permissions associated with the token are limited by the permissions of the token user and usually have further limitations depending on the token type.

In the Python API this functionality is provided by axivion.dashboard.Dashboard.create_api_token().

Note, that the user-part in the path requires some escaping to be applied (before regular percent-encoding). It is defined as follows:

• Replace all occurrences of : with :e

• Replace all occurrences of / with :s

• Replace all occurrences of \ with :b

Request Body:

• Body Type: ApiTokenCreationRequest

Status Codes:

• 200 OK –

  Body Type: ApiTokenInfo

  Successful response

DELETE /api/tokens

Bulk-delete API Tokens.

Since: 7.12.0

Deletes multiple API tokens at once. Tokens that do not exist or that the caller is not allowed to delete are silently skipped.

Request Body:

• Body Type: Array of string

Status Codes:

• 204 No Content – Successful response

GET /api/tokens/{id}

Get Info about an API Token.

Since: 7.1.0

In the Python API this functionality is provided by axivion.dashboard.Dashboard.get_api_token().

Status Codes:

• 200 OK –

  Body Type: ApiTokenInfo

  Successful response

DELETE /api/tokens/{id}

Delete an existing API Token.

Since: 7.1.0

Note, that this entry point will give no indication on whether the given token actually existed.

In the Python API this functionality is provided by axivion.dashboard.Dashboard.delete_api_token().

Status Codes:

• 204 No Content – Successful response

Types

ApiTokenType (enum)	Available types of ApiToken
ApiTokenInfo	Contains Meta-Data of an ApiToken
ApiTokenCreationRequest	Contains Request-Data for creating an ApiToken

ApiTokenType

Available types of ApiToken.

Since: 7.1.0

• General - Powerful token kind granting the same permissions as a regular password based login.

• IdePlugin - Limits user permissions to those typically needed by IDE plugins.

• SourceFetch - Used internally for local build. Cannot be created via this API.

• LogIn - Used internally by browsers for the “Keep me logged in” functionality. Cannot be created via this API.

• ContinuousIntegration - Limits user permissions to those typically needed for CI purposes.

Dashboard will automatically delete all of the created tokens when the account password is changed or deleted. The Dashboard will try to detect this for external password changes as well but cannot guarantee this will always work.

ApiTokenInfo

Contains Meta-Data of an ApiToken.

Since: 7.1.0

When this is returned as response of a creation request it will also contain the token secret

Properties:

• id (string) The unique Token-ID.

• url (string) The token URL

• isValid (boolean) Whether the token was still valid at query time.

  Invalid Tokens are effectively tombstones and cannot be used for authentication any more. Note, that this field is no indication on whether or not this object is transporting the secret.

• type (string) Possible values: ApiTokenType. Since 7.1.0. The type of the Token

• description (string) Description that was given on token creation.

• token (string) The secret token value.

  This is only initialized upon token creation. Use this to authenticate against the Dashboard as described in Authentication.

• creationDate (string) ISO8601 format date string

• displayCreationDate (string) Alternative representation of the token creation date, like “2 days ago” etc

• expirationDate (string) ISO8601 format date string

• displayExpirationDate (string) Alternative representation of the token expiration date, like “3 months from now” etc

• lastUseDate (string) ISO8601 format date if the token has already been used

• displayLastUseDate (string) Alternative representation of the token last use date, e.g. “2 days ago” or “Never”

• usedByCurrentRequest (boolean) Whether this token is used by the current request.

  Deletion of this token will invalidate the currently used credentials

ApiTokenCreationRequest

Contains Request-Data for creating an ApiToken.

Since: 7.1.0

Properties:

• password (string) Dashboard password of the user that requests the token creation

• type (string) Possible values: ApiTokenType. Since 7.1.0. the type of the token to create

• description (string) Purpose of the Token

• maxAgeMillis (integer) Used for configuring the Token expiration.

  • positive values are maxAge in milliseconds

  • 0 means: choose a default for me (recommended)

  • negative values are not allowed

  Note, that the server clock is decisive for when the actual token expiration will occur. Expired tokens will be invalidated or deleted on the server depending on their type.