API Tokens

ApiTokens are an essential element in the Authentication & Authorization features of Application Manager. The ApiToken resource can be used to allow non-interactive/machine to machine authentication in Application Manager.

Specification

ApiTokens are treated like users, in that they identify an entity which is authenticated to the system, and can be Authorized to perform actions on system by binding that token to a Role using a RoleBinding. This is an important distinction to realise. Thus ApiTokens are _not_ bound to users, they are their own entity, and users can create ApiTokens and bind them to Roles. Also since ApiTokens are like users, making them a top level resource and thus aren’t namespaced.

By default an ApiToken only allows its bearer to Authenticate with the system, but unless the token has bound to a Role through a RoleBinding, it won’t allow the bearer to do anything. In this sense an ApiToken has two parts; Authentication and Authorization.

ApiTokens once created can be revoked at any time, thus immediately revoking their bearer access to the system.

An API token is exposed only once on creation. Application Manager stores only hash value to later validate the token upon access. To use a token, you should provide Bearer {token} as Authorization HTTP header in your requests.

Creating an API Token

An example ApiTokens request to create a new token:

POST /api/v1/api-tokens
kind: ApiToken
metadata:
  name: my-token
kind: ApiToken
metadata:
 id: "9f08f864-cbbe-4e34-ad7e-6a79cebabb57"
 name: "my-token"
spec:
 token: sU9CmQwn5ioOO6D3zBIcfxtzKanvEkeUIXDmbYKFiY7fS_WHf9o711pSsMiD1_5C2iAUMDsm4rmTNq5LilsmB9hw5P7lSxURST_d2EzFTS0O2suxf9n9tBOGCEQBhoyJFVT2NVry_K95S6E5Jan5NZfd_E5u0r1_D5ucxtck5Ag

Attention

The returned token in spec.token will only be returned once. It is your responsibility to note this down and keep it safe.

Authenticating with an API Token

The created token can be used to authenticate via the Authorization header, e.g. Authorization: Bearer <token>.

curl -H 'Authorization: Bearer sU9CmQwn5ioOO6D3zBIcfxtzKanvEkeUIXDmbYKFiY7fS_WHf9o711pSsMiD1_5C2iAUMDsm4rmTNq5LilsmB9hw5P7lSxURST_d2EzFTS0O2suxf9n9tBOGCEQBhoyJFVT2NVry_K95S6E5Jan5NZfd_E5u0r1_D5ucxtck5Ag' /api/v1/api-tokens

Revoking an API Token

You revoke an API token via a delete request:

DELETE /api/v1/api-tokens/my-token

After the API token has been deleted, it cannot be used for authentication any longer.