API Keys

Create, revoke, and manage your API keys.

API Keys

API keys authenticate requests to the Developer API (/api/v1/*). You can create and manage keys from Settings → API Keys in the OJobs dashboard.

Managing keys (the endpoints below) requires being logged into the dashboard with your organisation account — these are different from the /api/v1/* endpoints, which authenticate with the key itself.

Creating a key

When you create a key, you choose:

Prop	Type	Default
`name`	`string`	-
`environment`	`"prod" \| "test"`	-
`allowedOrigins`	`string[]`	-

The full plaintext key is only returned once, at creation time:

{
  "apiKey": {
    "id": "3aa210f0-...",
    "name": "Production server",
    "keyPrefix": "ojobs_prod_a8f2",
    "environment": "prod",
    "createdAt": "2026-07-08T09:00:00.000Z"
  },
  "plaintextKey": "ojobs_prod_a8f2c9e1d0b3..."
}

After creation, only keyPrefix (e.g. ojobs_prod_a8f2) is ever shown again — OJobs never stores the plaintext key, only a SHA-256 hash of it. If you lose the plaintext key, you'll need to revoke it and create a new one.

Listing your keys

Returns every key on your account, without plaintext values:

Prop	Type	Default
`id`	`string`	-
`name`	`string`	-
`keyPrefix`	`string`	-
`environment`	`"prod" \| "test"`	-
`requestCount`	`number`	-
`lastUsedAt`	`string \| null`	-
`revokedAt`	`string \| null`	-
`createdAt`	`string`	-

Revoking a key

Revoking a key is soft — the key row isn't deleted, it's just marked revokedAt and immediately stops authenticating any request. This preserves its request history and logs.

There's no "un-revoke." If you need the key back, create a new one.

Rotating a key

There's no built-in rotation endpoint — rotate by creating a new key, updating your integration to use it, then revoking the old one once you've confirmed the new one works.

Best practices

Use a test key while building or demoing an integration — it works immediately, even before your organisation is approved, and always returns the same safe sandbox data (see Test mode). Switch to a prod key only once you're ready to go live.
Set allowedOrigins for any key used in browser-side code (e.g. the embeddable widget). Leave it empty only for trusted server-to-server use.
Give each integration its own key rather than sharing one — it makes revoking a single compromised integration painless and makes requestCount actually useful for debugging.