# API Keys

API Keys enable programmatic, non-interactive access to the platform — suitable
for server-to-server integrations, CI/CD pipelines, and automated content workflows
that cannot use user-delegated OAuth tokens.

Each API key is scoped to the organization of the user who creates it and carries
that user's permissions. Keys should be stored securely and rotated regularly.

- `create-api-key` — generate a new API key; the raw key value is only returned once at creation
- `list-api-keys` — enumerate existing keys (key values are not re-exposed)
- `revoke-api-key` — permanently invalidate a key; any integrations using it will lose access immediately


## Create an API key

 - [POST /api/v1/api-key/create-api-key](https://api.tenovos.com/openapi/content-intelligence/api-keys/tenovos.authz.apikeyservice.createapikey.md): Creates a new API key for programmatic access, assigning it a role that defines its permissions.

Request:
name          - Human-readable label for the API key.
expiresAt    - Optional expiry timestamp. If omitted the key does not expire.
roleId       - Role to assign to the API key's associated service account, determining
what operations the key is authorized to perform.

Response:
id            - Assigned API key ID.
name          - Key display name.
keyHint      - Last 4 characters of the key, for identification purposes.
expiresAt    - Expiry timestamp if one was set.
key           - The full plaintext API key. This is the only time the full key is returned;
it is stored hashed and cannot be retrieved again.

## Search API keys

 - [POST /api/v1/api-key/list-api-keys](https://api.tenovos.com/openapi/content-intelligence/api-keys/tenovos.authz.apikeyservice.listapikeys.md): Lists API keys in the organization with optional filtering for revoked or expired keys.

Request:
pageCursor       - Optional cursor for paginating through results.
maxSize          - Optional maximum number of results to return per page.
includeRevoked   - When true, includes revoked keys in the results.
includeExpired   - When true, includes expired keys in the results.

Response:
apiKeys      - List of ApiKey objects (id, name, keyHint, timestamps). Full key values
are never returned.
pagination    - Pagination object containing the cursor for the next page.

## Revoke an API key

 - [POST /api/v1/api-key/revoke-api-key](https://api.tenovos.com/openapi/content-intelligence/api-keys/tenovos.authz.apikeyservice.revokeapikey.md): Revokes an API key, permanently deactivating it so it can no longer be used for authentication.

Request:
id         - ID of the API key to revoke. Revocation cannot be undone.

Response:
apiKey    - The ApiKey record with the revokedAt timestamp populated.