Skip to main content
Version: 2.12

API Tokens

The API Token resource allows non-interactive/machine to machine access to Ververica Platform.

Overview​

API Tokens are treated like a user within the system; they identify an entity that is authenticated and authorized to perform actions. API Tokens are not bound to users, but represent their own independent entity and are treated as a top level resource.

API Tokens are scoped to a Namespace and are assigned a role within that Namespace. In order to be able to create an API Token, a user needs to have the owner role in the respective Namespace.

Once an API Token is created, it can be revoked at anytime, immediately revoking access to the system.

Creating an API Token​

API Tokens are created via a POST request that includes the name and designated role:

  • The name needs to be fully qualified and include the namespace name.
  • The role can be either of viewer, editor, or owner and controls the permissions of the API Token.

Please consult the Roles section for more details on these roles and which permissions they grant.

    POST /apitokens/v1/namespaces/default/apitokens

  {
    "name": "namespaces/default/apitokens/ci-token",
    "role": "editor"
  }

  {
    "apiToken": {
      "name": "namespaces/default/apitokens/ci-token",
      "secret": "07044996-42e3-4078-a0a9-74927531f355",
      "role": "editor",
      "createTime": "2019-10-07T11:07:12.667Z"
    }
  }
caution

An API Token's secret is exposed only once on creation: there are no API calls to retrieve the secret of an already created API Token. Therefore, it is important that the secret is written down immediately after creation. If the secret is lost, the API Token must be recreated.

Authenticating with an API Token​

An API Token can be used by specifying its secret in the Authorization HTTP header of API requests:

  Authorization: Bearer <secret>

Example: Listing Deployments using an API Token

  curl -H 'Authorization: Bearer 07044996-42e3-4078-a0a9-74927531f355' /api/v1/namespaces/default/deployments

API requests issued with a certain API Token are limited to the permissions of the role assigned to the API Token on creation time.

Revoking an API Token​

API Tokens are revoked via a DELETE request.

  DELETE /apitokens/v1/namespaces/default/apitokens/ci-token

After the API Token has been deleted, it can no longer be used to access resources.