Unique AI Documentation

Creating Personal API Keys Via API

2 min read

Creating a Personal API Key Without UI Access

The Unique API endpoint for creating a personal API key requires an existing API key; this is designed with security in mind.

Prerequisite: Enable the Appropriate Key Type

Personal API key generation is allowed when either of these settings is enabled for the company:

  • USER_API_KEY_GENERATION_ENABLED: use this when creating API keys for regular users. It must be enabled on node-app-repository. It can remain disabled on the frontends to hide personal API key generation from the UI.

  • FEATURE_FLAG_ENABLE_SERVICE_USER_API_KEY_UN_22696: use this when creating API keys for service users. It enables synchronization of Zitadel machine users into the user system so they can be configured in Access Management and hold their own API keys.

Option 1: Use an App API Key

An administrator uses an app API key to create a personal API key for a specific regular user or synchronized service user.

App API keys are highly privileged. The recommended approach is for an administrator to perform this operation rather than sharing the app key with developers.

You can read more about App Keys and what they are used for here: https://unique-ag.github.io/ai/unique-toolkit/latest/authentication/#2-creating-an-app

bash
curl --request POST \
  'https://api.<env>.unique.app/unique-api/me/api-key' \
  --header 'Authorization: Bearer <APP_API_KEY>' \
  --header 'x-api-version: 2026-03-01' \
  --header 'x-company-id: <COMPANY_ID>' \
  --header 'x-user-id: <USER_OR_SERVICE_USER_ID>' \
  --header 'x-app-id: <APP_ID>'

The returned key belongs to the identity specified by x-user-id and uses that identity's roles and knowledge-base access.

Option 2: Use GraphQL With User Authentication

The caller uses the same mutation as the UI, authenticated with an OIDC access token. No existing API key is required.

Endpoint:

text
POST https://api.<env>.unique.app/apps/graphql

Mutation:

graphql
mutation AppCreateWithUserScope {
  appCreateWithUserScope {
    id
    key
    expiresAt
    createdAt
    app {
      id
    }
  }
}

Example:

bash
curl --request POST \
  'https://api.<env>.unique.app/apps/graphql' \
  --header 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "operationName": "AppCreateWithUserScope",
    "query": "mutation AppCreateWithUserScope { appCreateWithUserScope { id key expiresAt createdAt app { id } } }"
  }'

The key is created for the identity represented by the access token. Another identity cannot be selected through this mutation.

Important Behavior

  • Calling the operation again regenerates the key and invalidates the previous one.

  • The plaintext key is returned only once.

  • For self-service, GraphQL is the safer option. The app key option should remain administrator-operated.

Choosing the Resulting Identity

A regular user's personal API key inherits that person's roles and knowledge-base access, while its cost and consumption are combined with the user's other activity.

A service-user API key can be granted only the permissions required by the integration and can have separate cost limits. The service user must first be synchronized and configured in Access Management by enabling FEATURE_FLAG_ENABLE_SERVICE_USER_API_KEY_UN_22696.

See Service Users & API Key Scoping for the service-user setup.

Last updated