Manage API Keys

API keys allow users (and system integrations) to authenticate to the Immuta API. The identity manager API includes endpoints to create, list, and delete API keys.

Endpoints and methods

Method	Endpoint	Description
POST	/apikey	Creates an API key for the current user
POST	/apikey/system	Creates (or returns) a system API key (admin)
GET	/iam/{iamid}/user/{userid}/apikeys	Lists API key metadata for a user
DELETE	/apikey/{keyid}	Deletes an API key (current user only)
DELETE	/apikey/system/{keyid}	Deletes a system API key (admin)

POST /apikey

Create a new API key for the currently authenticated user.

curl -X 'POST' \
  'https://your.immuta.url.com/apikey' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
  "projectId": 123,
  "name": "My CLI key"
  }'

Body parameters

Parameter	Description	Required or optional	Default values	Accepted values
projectId integer	The project to assign this API key to. If omitted or set to null, the request will use the user's current project and set the API key context to CURRENT_PROJECT.	Optional	null	-
name string	The name to associate with this API key.	Optional	null	Max length 254

Response

{
  "apikey": "your-new-api-key",
  "keyid": 456,
  "project": 123,
  "name": "My CLI key",
  "context": "CURRENT_PROJECT"
}

Error responses

• 400: User is not a member of the project specified; acknowledgement required; or other invalid request state.

• 404: Project not found.

POST /apikey/system

Create an API key for the system. Currently this endpoint can only be used to create the API key for Trino connections.

Required Immuta permission: APPLICATION_ADMIN

Idempotent behavior

If a system API key with the given name already exists and it matches the same connectionKey and scopes, the endpoint will return the existing key. To rotate the key, set regenerate to true.

curl -X 'POST' \
  'https://your.immuta.url.com/apikey/system' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <admin_access_token>' \
  -d '{
  "name": "trino-connection-1",
  "scopes": ["plugin:trino"],
  "connectionKey": "connection-abc123",
  "regenerate": false
  }'

Body parameters

Parameter	Description	Required or optional	Default values	Accepted values
name string	The unique name to associate with the system API key.	Required	-	-
scopes array	The scope of the API key. Must be non-empty and valid. Currently, the only supported scope is ["plugin:trino"]	Required	-	["plugin:trino"]
connectionKey string	The connection key for the connection the API key will be used with.	Required	-	-
regenerate boolean	If true, a new API key will be created even if there is already an API key associated with the same connection and scope. If false, it will return the existing key.	Optional	false	true or false

Response

{
  "apikey": "your-api-key",
  "keyid": 987,
  "name": "trino-connection-1"
}

Error responses

• 400: Connection key not found, scopes invalid, or a key with the same name exists for a different connection or scope.

GET /iam/{iamid}/user/{userid}/apikeys

Retrieve metadata for all the user's API keys.

Requirement: You must own the API key or have the USER_ADMIN permission

curl -X 'GET' \
  'https://your.immuta.url.com/iam/<iamid>/user/<userid>/apikeys' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Path parameters

Parameter	Description
iamid string	The IAM identifier.
userid string	The user identifier in the IAM.

Response

Returns an array of API key metadata objects.

[
  {
    "keyid": 456,
    "created": "2025-01-15T18:22:10.000Z",
    "project": null,
    "lastUsed": null,
    "name": "My CLI key",
    "context": "CURRENT_PROJECT"
  }
]

DELETE /apikey/{keyid}

Delete an API key owned by the current user. This also deletes all auth tokens derived from that API key.

curl -X 'DELETE' \
  'https://your.immuta.url.com/apikey/456' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Path parameter

Parameter	Description
keyid integer	API key ID.

Response

{
  "revokedTokens": 12
}

Error responses

• 403: You may not delete another user's API key.

• 404: API key not found or no keys deleted.

DELETE /apikey/system/{keyid}

Delete a system API key.

Required Immuta permission: APPLICATION_ADMIN

curl -X 'DELETE' \
  'https://your.immuta.url.com/apikey/system/987' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin_access_token>'

Path parameter

Parameter	Description
keyid integer	System API key ID.

Response

{
  "revokedKeys": 1
}

Error responses

• 404: System API key not found.