Skip to main content

API Keys API Reference

Complete reference for the API Keys API endpoints.

Base URL​

https://api.orcarail.com/api/v1

Create an API Key​

Create a new API key for a specific organization.

POST /organizations/:organizationId/api-keys

Authentication​

  • Bearer Token (JWT) - Required

Path Parameters​

ParameterTypeRequiredDescription
organizationIdstringYesOrganization ID to create the key for. The bearer token must have access.

Use the organization id from Dashboard → Organization Settings or your organizations list API response. The path parameter is required; API keys are created for that exact organization.

Request Body​

ParameterTypeRequiredDescription
namestringNoDescriptive name for the API key
webhookUrlstringNoWebhook URL to receive payment events

Response​

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "webhookUrl": "https://api.example.com/webhooks/orcarail",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning Important The secret is only shown once. Save it immediately! :::

List API Keys​

List all API keys for a specific organization.

GET /organizations/:organizationId/api-keys

Authentication​

  • Bearer Token (JWT) - Required

Path Parameters​

ParameterTypeRequiredDescription
organizationIdstringYesOrganization ID to list keys for. The bearer token must have access.

The list is scoped only to the organization in the path; OrcaRail does not infer a different organization from the session when this parameter is present.

Response​

[
  {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  {
    "id": 2,
    "name": "Development API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-02T00:00:00.000Z"
  }
]

Update an API Key​

Update an API key's name or webhook URL.

PATCH /api-keys/:id

Authentication​

  • Bearer Token (JWT) - Required

Path Parameters​

ParameterTypeRequiredDescription
idnumberYesAPI key ID

Request Body​

ParameterTypeRequiredDescription
namestringNoDescriptive name for the API key
webhookUrlstringNoWebhook URL to receive payment events (set to null to remove)

Response​

{
  "id": 1,
  "name": "Updated API Key Name",
  "keyPrefix": "ak_live_",
  "status": "active",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Revoke an API Key​

Revoke an API key to disable it.

POST /api-keys/:id/revoke

Authentication​

  • Bearer Token (JWT) - Required

Path Parameters​

ParameterTypeRequiredDescription
idnumberYesAPI key ID

Response​

{
  "id": 1,
  "name": "Production API Key",
  "keyPrefix": "ak_live_",
  "status": "revoked",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Test an API Key​

Test if an API key is valid.

POST /api-keys/test

Authentication​

  • None required

Request Body​

ParameterTypeRequiredDescription
keystringYesAPI key (e.g., ak_live_...)
secretstringYesAPI secret (e.g., sk_live_...)

Response​

{
  "ok": true
}

Error Response​

If the API key is invalid:

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

API Key Object​

Fields​

FieldTypeDescription
idnumberUnique identifier
namestringDescriptive name
keyPrefixstringFirst 8 characters of the key (e.g., ak_live_)
statusstringStatus: active or revoked
webhookUrlstringWebhook URL for receiving payment events (nullable)
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

Status Values​

StatusDescription
activeAPI key is active and can be used
revokedAPI key has been revoked and cannot be used

Status Codes​

Status CodeDescription
200Success
201Created
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error

Error Response Format​

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

See Also​