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:

1POST /apitokens/v1/namespaces/{namespace}/apitokens

The response includes the token secret:

1{
2  "apiToken": {
3    "name": "namespaces/default/apitokens/ci-token",
4    "secret": "07044996-42e3-4078-a0a9-74927531f355",
5    "role": "editor",
6    "createTime": "2024-01-01T00:00:00Z"
7  }
8}

Use an API Token

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

1curl -H 'Authorization: Bearer <secret>' \
2  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:

1DELETE /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.

Workspace-Scoped Admin Tokens

A workspace-scoped admin token is a single administrative credential that works in every namespace in a workspace, instead of the one namespace a regular token is limited to. It carries the admin role and is declared through Helm configuration rather than created in the console or through the API. Use it for automation that needs to authenticate unattended, such as a CI pipeline that deploys jobs, or a monitoring or health-check integration, without a person generating a token by hand for every namespace.

Create a Workspace-Scoped Admin Token

1. Store the token value as a Kubernetes Secret in the platform's namespace:

1kubectl -n <platform-namespace> create secret generic vvp-admin-token \
2  --from-literal=token="$TOKEN_VALUE"

1. Reference the Secret in your Helm values:

1access-control:
2  workspaceAdminToken:
3    name: ci-pipeline
4    secretName: vvp-admin-token
5    secretKey: token

1. Install or upgrade the chart. The platform hashes the value and grants it the admin role.
2. Verify the token was created:

1curl -H "Authorization: Bearer $TOKEN_VALUE" \
2     -H "workspace: defaultworkspace" \
3     https://<host>/apitokens/v1/workspace/apitokens

Use a Workspace-Scoped Admin Token

Requests with a workspace-scoped admin token require these headers:

• Authorization: Bearer <token value>, on every request.
• workspace: required. A request without it is rejected.
• namespace: required for an operation scoped to a single namespace.

1curl -X POST \
2  -H "Authorization: Bearer $TOKEN_VALUE" \
3  -H "workspace: defaultworkspace" \
4  -H "namespace: team-a" \
5  -H "Content-Type: application/json" \
6  -d @deployment.json \
7  https://<host>/api/v1/namespaces/team-a/deployments

What a Workspace-Scoped Admin Token Can Do

With this token, automation can, across every namespace in the workspace:

• Create and delete namespaces.
• Assign roles to users and to identity-provider groups, for example binding an Active Directory group to a role on a namespace.
• Mint a namespace-scoped token for a team.
• Manage deployments and define namespace-scoped secrets.
• List every namespace on the platform.

Rotate a Workspace-Scoped Admin Token

Update the Kubernetes Secret, then restart access-control-service:

1kubectl -n <platform-namespace> create secret generic vvp-admin-token \
2  --from-literal=token="$NEW_TOKEN_VALUE" \
3  --dry-run=client -o yaml | kubectl apply -f -
4
5kubectl -n <platform-namespace> rollout restart deployment/access-control-service

The old value stops working the moment the new pod starts serving, and the new value starts working at the same instant.

Revoke a Workspace-Scoped Admin Token

Remove the workspaceAdminToken block from your Helm values and upgrade. There is no delete endpoint: removing a credential through an API call would only have it recreated the next time the pod restarts, so revocation goes through the declared configuration instead.

Limitations

• One workspace-scoped admin token per workspace.
• No expiration date yet. This is planned for a future release.
• Token values must be unique. Reusing a value that is already in use is rejected.

Security Recommendations

Treat this token as a full workspace-admin credential. If you suspect it has been compromised, rotate it and audit the role bindings and tokens it might have created, since rotating the token does not revoke those.

Troubleshooting

• A request missing a required header fails as a permission error rather than a header-validation error, so check the headers above first if a request is unexpectedly denied.
• If the referenced Kubernetes Secret does not exist, the access-control-service pod enters CreateContainerConfigError.
• If a rotation does not seem to take effect, confirm that access-control-service was actually restarted after the Secret was updated. The verification endpoint's updatedAt field confirms whether the rotation completed.