User API Keys

A signed-in project user can create user API keys: long-lived secrets tied to that user in one project. They are intended for your own backends or integrations (for example calling your API with a stable credential), not for replacing the Noma dashboard’s personal access tokens.

Keys are created with a readable name, optional scopes (free-form strings stored on the key), and an optional expiry datetime.

Prefix: keys are issued with a uak_ prefix (for example uak_xxxxxxxxxxxx_...).

API

All routes require a project user access token (JWT from sign-in), not a personal access token:

project-id: <your-project-uuid>
Authorization: Bearer <project-user-access-token>
Accept: application/json

List keys

GET /api/auth/api-keys

200 OK — { "data": [ ... ] } each item includes id, name, key_prefix, scopes, expires_at, last_used_at, revoked_at, created_at. The full secret is never listed.

Create key

POST /api/auth/api-keys

Body (JSON):

201 Created — Returns metadata plus plain_text_key: the only time the full secret is shown. Store it securely.

Revoke key

POST /api/auth/api-keys/{id}/revoke

200 OK — API key revoked.

404 — Key not found for this user.

Relationship to the Content API

User API keys cannot be used as Authorization: Bearer on Content API routes (collections, entries, assets, webhooks, and so on). Those routes require a personal access token from User Settings → API Keys on your user account, created with the same workspace active as the project you’re calling, with the appropriate abilities, as documented in Authentication.

If you send a uak_ key on Content API requests, the API responds with 401.

Use user API keys in your services where you validate the secret yourself, or keep them for future product features that explicitly accept them.

JavaScript SDK

import { createClient } from "@nomacms/js-sdk"
 
const noma = createClient({
  projectId: process.env.NOMA_PROJECT_ID!,
  apiKey: process.env.NOMA_API_KEY, // personal access token for CMS routes
  projectUserAuth: {
    accessToken: userAccessToken,
    refreshToken: userRefreshToken,
  },
})
 
const created = await noma.createUserApiKey({
  name: "CI bot",
  scopes: ["read", "write"],
})
 
console.log(created) // includes plain_text_key once
 
const keys = await noma.listUserApiKeys()
await noma.revokeUserApiKey(keyId)

Related

• Overview — Personal access tokens vs project users.
• Session Management — How users obtain the access token needed to manage keys.