Skip to main content

API keys management

API keys serve as a way to authenticate applications where individual user identification and authentication are not required. They function as permanent access tokens.

Create an API Key for a Project

You can create a project-specific API key using the GraphQL API:

mutation {
createApiKey(
projectSlug: "my-blog",
description: "User-friendly description of the key",
memberships: [{role: "editor", variables: [{name: "language", values: ["cs"]}]}]
) {
ok
error {
code
}
result {
apiKey {
id
token
identity {
id
}
}
}
}
}

This returns three identifiers:

  • API Key ID: Used for disabling this API key later.
  • Identity ID: Used to modify the API key's memberships and permissions.
  • Token: A bearer token used for authenticating your GraphQL requests.

Create Global API Key

mutation {
createGlobalApiKey(
description: "Global API key description",
roles: ["super_admin", "monitor"]
) {
ok
error {
code
}
result {
apiKey {
id
token
identity {
id
}
}
}
}
}

This also returns three identifiers similar to creating a project-specific API key.

Custom Token Generation

Both createApiKey and createGlobalApiKey support the optional tokenHash parameter. If you provide a SHA-256 hash of the token you wish to use, the API will not generate a new token, and the token field in the response will be empty. This allows you more control over token management but requires you to securely generate and store the original token yourself.

Add Global Roles to an Identity

mutation {
addGlobalIdentityRoles(
identityId: "some-identity-id",
roles: ["super_admin", "monitor"]
) {
ok
error {
code
}
}
}

Remove Global Roles from an Identity

mutation {
removeGlobalIdentityRoles(
identityId: "some-identity-id",
roles: ["monitor"]
) {
ok
error {
code
}
}
}

Disable API Key

mutation {
disableApiKey(id: "some-api-key-id") {
ok
}
}

Use the API Key ID to disable the API key. Do not confuse this with the Identity ID.