API Keys

API keys provide programmatic access to the Notebind API. Keys are hashed before storage and the plain key is only returned once at creation time.

API key object

{
  "id": "key-uuid",
  "name": "Production Agent",
  "key_prefix": "nb_sk_a1b2c3",
  "last_used_at": "2026-03-13T12:00:00.000Z",
  "created_at": "2026-03-13T11:00:00.000Z"
}

Field	Type	Description
id	UUID	Key identifier
name	string	Human-readable name (max 100 characters)
key_prefix	string	First 14 characters of the key for identification
last_used_at	ISO 8601 or null	Last time the key was used to authenticate
created_at	ISO 8601	When the key was created

Caution

The full key (key) is only returned in the creation response. Store it securely — it cannot be retrieved later.

---

List API keys

GET /api/keys

Returns all API keys for the authenticated user, sorted by created_at descending.

Request

curl https://notebind.com/api/keys \
  -H "Authorization: Bearer nb_sk_YOUR_KEY"

Response 200 OK

{
  "data": [
    {
      "id": "key-uuid",
      "name": "Production Agent",
      "key_prefix": "nb_sk_a1b2c3",
      "last_used_at": "2026-03-13T12:00:00.000Z",
      "created_at": "2026-03-13T11:00:00.000Z"
    }
  ],
  "error": null
}

The response never includes the full key or key hash.

---

Create an API key

POST /api/keys

Request body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the key (max 100 characters)

Request

curl -X POST https://notebind.com/api/keys \
  -H "Authorization: Bearer nb_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

Response 201 Created

{
  "data": {
    "apiKey": {
      "id": "key-uuid",
      "name": "CI/CD Pipeline",
      "key_prefix": "nb_sk_a1b2c3",
      "last_used_at": null,
      "created_at": "2026-03-13T12:00:00.000Z"
    },
    "key": "nb_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
  },
  "error": null
}

Caution

The key field contains the full API key. This is the only time the full key is returned. Copy it immediately and store it securely.

Key format

Keys follow the pattern: nb_sk_ + 32 hex characters (16 random bytes).

nb_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

---

Delete an API key

DELETE /api/keys/:id

Permanently revokes an API key. Any requests using this key will immediately fail with 401 Unauthorized.

Path parameters

Parameter	Type	Description
id	UUID	API key ID

Request

curl -X DELETE https://notebind.com/api/keys/KEY_ID \
  -H "Authorization: Bearer nb_sk_YOUR_KEY"

Response 200 OK

{
  "data": { "deleted": true },
  "error": null
}

---

Security

• Keys are hashed with SHA-256 before storage
• Only the first 14 characters (prefix) are stored in plaintext for display
• last_used_at is updated on every successful authentication
• Keys are scoped to the user who created them — cross-user access is not possible
• There is no key rotation mechanism; delete the old key and create a new one

---

Error responses

Status	Code	Description
400	VALIDATION_ERROR	Missing or empty name, or name exceeds 100 characters
401	UNAUTHORIZED	Missing or invalid credentials
404	NOT_FOUND	API key not found