API Keys

Generate long-lived credentials for server-to-server communication. API keys let your backend verify user tokens and access org data without involving the user's session.

API keys are scoped to a single organization. They authenticate requests to the /public/* endpoints via the X-API-Key header.

Never expose API keys to the browser. Store them only in server-side environment variables.

Key format

Keys are prefixed with pk_live_ followed by 64 hex characters, e.g.:

pk_live_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0

The raw key is shown once at creation time and is never stored in plaintext. If you lose it, revoke and create a new one.

Rate limits

The /public/* endpoints are rate-limited per API key:

Limit	Window
300 requests	15 minutes

Responses include standard rate-limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1716912000

Create an API key

Generates a new API key for this org. Requires org_admin role.

POST /org/api-keys

Request body

Field	Type		Description
name	string	required	A label to identify this key (e.g. "Production backend").
expiresAt	string (ISO 8601)	optional	Expiry date. Omit for a key that never expires.

Request

{ "name": "Production backend" }

Response (201)

{
  "status": "success",
  "data": {
    "key": "pk_live_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
    "apiKey": {
      "id": "key_01ABCD",
      "name": "Production backend",
      "prefix": "pk_live_a3",
      "createdAt": "2025-05-23T12:00:00.000Z",
      "expiresAt": null,
      "lastUsedAt": null
    }
  }
}

Copy the key value now — it is shown once and cannot be retrieved again. Store it immediately in your secrets manager or environment variable.

List API keys

Returns all keys for this org. The raw key value is never returned — only the prefix.

GET /org/api-keys

Response (200)

{
  "status": "success",
  "data": {
    "apiKeys": [
      {
        "id": "key_01ABCD",
        "name": "Production backend",
        "prefix": "pk_live_a3",
        "isActive": true,
        "createdAt": "2025-05-23T12:00:00.000Z",
        "expiresAt": null,
        "lastUsedAt": "2025-05-23T14:35:00.000Z"
      }
    ]
  }
}

Revoke an API key

Immediately invalidates the key. Any requests using it will fail with 401.

DELETE /org/api-keys/:keyId

Response (200)

{ "status": "success", "data": { "message": "API key revoked" } }

Using an API key

Include the key in the X-API-Key header on every request to /public/*:

Node.js / fetch

const response = await fetch('https://authworx.uthings.io/api/v1/public/verify', {
  method: 'POST',
  headers: {
    'X-Org-Slug': process.env.AUTHWORX_ORG_SLUG!,
    'X-API-Key':  process.env.AUTHWORX_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ token: userAccessToken }),
});

const { data } = await response.json();
if (!data.valid || data.membership?.status !== 'active') {
  throw new Error('Unauthorized');
}

console.log('Verified user:', data.user.email);

Available public endpoints

Method	Path	Description
POST	`/public/verify`	Verify a user JWT and return user + membership data.
GET	`/public/users/:userId`	Fetch a user's profile by ID, scoped to your org.
GET	`/public/org`	Get your organization's details.