Create API Key

Create a new API key for programmatic access to EntryGuard. The full API key secret is only shown once upon creation and cannot be retrieved later.

Note: This feature is only available for organizations on the paid plan.

Request

POST /api-keys

Authentication

Requires an Admin Bearer JWT token.

Authorization: Bearer <access_token>

Request Body

{
  "name": "CI/CD Pipeline Key",
  "description": "API key for automated deployments",
  "scopes": ["sessions:read", "sessions:write"],
  "expiresAt": "2026-12-31T23:59:59Z"
}

Request Fields

Field	Type	Required	Description
name	string	Yes	Human-readable name for the key (max 255 characters)
description	string	No	Optional description of the key's purpose
scopes	string[]	Yes	Array of permission scopes (must be non-empty)
expiresAt	string	No	ISO timestamp when the key should expire (null for no expiration)

Available Scopes

Scope	Description
sessions:read	Read session data
sessions:write	Create and manage sessions
resources:read	Read resource data
audit:read	Read audit logs

Response

Returns the created API key object including the plain text key secret.

Success Response

Status Code: 201 Created

Response Body:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI/CD Pipeline Key",
  "description": "API key for automated deployments",
  "keyPrefix": "egk_live_abc123",
  "plainTextKey": "egk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "scopes": ["sessions:read", "sessions:write"],
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2026-02-18T10:30:00Z"
}

Response Fields

Field	Type	Description
id	UUID	Unique identifier for the API key
name	string	Human-readable name for the key
description	string	Optional description
keyPrefix	string	First few characters of the key for identification
plainTextKey	string	Full API key secret (shown only once)
scopes	string[]	Array of permission scopes granted to this key
expiresAt	string	ISO timestamp when key expires (null if no expiration)
createdAt	string	ISO timestamp of creation

Errors

Status Code	Error Code	Description
400	BAD_REQUEST	Invalid request body or missing required fields
401	UNAUTHORIZED	Missing or invalid JWT token
403	FORBIDDEN	User does not have admin privileges or organization is not on the paid plan
422	UNPROCESSABLE_ENTITY	Invalid scope values or validation errors

Example

Request

curl -X POST https://api.entryguard.io/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key",
    "description": "API key for automated deployments",
    "scopes": ["sessions:read", "sessions:write"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI/CD Pipeline Key",
  "description": "API key for automated deployments",
  "keyPrefix": "egk_live_abc123",
  "plainTextKey": "egk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "scopes": ["sessions:read", "sessions:write"],
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2026-02-18T10:30:00Z"
}

Important: Store the plainTextKey securely. It will never be displayed again. If you lose it, you must create a new API key.