Skip to main content
Version: 3.1

API Tokens

API tokens provide machine-to-machine access to Ververica Platform without interactive user credentials. Each token is scoped to a namespace and assigned a role (viewer, editor, or owner) that determines its permissions. Tokens can be created, used, and revoked at any time.

Create an API Token​

You must have the owner role in the target namespace to create a token.

Using the UI​

  1. In the left navigation, click the Namespace selector and select the namespace.
  2. Go to Settings > API Tokens.
  3. Click Create Token.
  4. Enter a name for the token and select a role.
  5. Optionally, set an expiry date.
  6. Click Create. Copy the secret immediately. It appears only once.

Using the API​

Send a POST request with the token name and role. The name must be fully qualified and include the namespace:

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

The response includes the token secret:

{
  "apiToken": {
    "name": "namespaces/default/apitokens/ci-token",
    "secret": "07044996-42e3-4078-a0a9-74927531f355",
    "role": "editor",
    "createTime": "2024-01-01T00:00:00Z"
  }
}
warning

The token secret appears only once at creation. Copy it immediately. You cannot retrieve it later. If you lose the secret, regenerate or delete and recreate the token.

Use an API Token​

Pass the token secret in the Authorization header as a Bearer token:

curl -H 'Authorization: Bearer <secret>' \
  https://<vvp-host>/api/v1/namespaces/default/deployments

A token limits requests to the permissions of the role assigned at creation.

Manage API Tokens​

Set an Expiry Date​

You can optionally set an expiry date when creating a token. After the expiry date passes, the token automatically expires and you can no longer use it.

Regenerate a Token​

Regeneration issues a new secret for an existing token and immediately invalidates the previous secret. Use this to rotate credentials without changing the token's name or role.

To regenerate a token, open the token in Settings > API Tokens and click Regenerate. Copy the new secret immediately.

Revoke a Token​

To revoke a token using the API, send a DELETE request:

DELETE /apitokens/v1/namespaces/{namespace}/apitokens/{token-name}

The token is immediately invalid after deletion. You can no longer use it to access resources.

Security Recommendations​

  • Store token secrets in a secrets manager (for example, Kubernetes Secrets or Vault). Never hard-code them in source code.
  • Assign the least-privileged role sufficient for the use case.
  • Set expiry dates for tokens used in automation pipelines.
  • Rotate tokens regularly using the regeneration feature.
  • Revoke tokens immediately when they are no longer needed.
On this page