API Documentation

Keys & Usage API

Programmatically create, list, and revoke API keys. Monitor workspace usage and plan limits.

POST

/api/v1/keys

Create a new API key

Request Body

Field	Type	Required	Description
`name`	string	No	Label for the key (default: "Unnamed Key")
`environment`	string	No	`"sandbox"` or `"live"` (default: "sandbox")

Example

curl -X POST https://paydirect.com/api/v1/keys \
  -H "Authorization: Bearer pd_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Backend", "environment": "live"}'

Response (201 Created)

{
  "apiKey": {
    "id": "key-uuid-...",
    "name": "Production Backend",
    "environment": "live",
    "is_active": true,
    "created_at": "2026-02-16T14:36:22Z",
    "key": "pd_live_newly_generated_key..."
  }
}

The full key value is only returned at creation. Store it securely.

GET

/api/v1/keys

List all API keys for the workspace

curl https://paydirect.com/api/v1/keys \
  -H "Authorization: Bearer pd_test_abc123..."

Response (200 OK)

{
  "keys": [
    {
      "id": "key-uuid-...",
      "name": "Production Backend",
      "environment": "live",
      "is_active": true,
      "created_at": "2026-02-16T14:36:22Z",
      "key_preview": "pd_live_...abc"
    },
    {
      "id": "key-uuid-2-...",
      "name": "Test Key",
      "environment": "sandbox",
      "is_active": true,
      "created_at": "2026-02-15T10:00:00Z",
      "key_preview": "pd_test_...xyz"
    }
  ]
}

Key values are masked. Only a preview suffix is shown.

DELETE

/api/v1/keys/:id

Revoke an API key (soft delete)

curl -X DELETE https://paydirect.com/api/v1/keys/key-uuid-... \
  -H "Authorization: Bearer pd_test_abc123..."

Response (200 OK)

{
  "success": true,
  "message": "API key revoked"
}

Revoked keys are soft-deleted (is_active = false). They can no longer be used for authentication.

Usage API

Monitor workspace activity and plan limits

GET

/api/v1/usage

Get current usage metrics and plan limits

curl https://paydirect.com/api/v1/usage \
  -H "Authorization: Bearer pd_test_abc123..."

Response (200 OK)

{
  "usage": {
    "payments_created": 142,
    "api_calls": 3567,
    "webhooks_delivered": 284
  },
  "limits": {
    "allowed": true,
    "reason": "Within limits"
  },
  "plan": "free"
}

When limits.allowed is false, payment creation is blocked until the usage resets or the workspace upgrades to Pro.

POST

/api/v1/usage

Record a usage metric

Request Body

Field	Type	Description
`metric`	string	`"payments_created"`, `"api_calls"`, or `"webhooks_delivered"`
`count`	number	Positive integer to increment by

curl -X POST https://paydirect.com/api/v1/usage \
  -H "Authorization: Bearer pd_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"metric": "api_calls", "count": 1}'

Response (201 Created)

{
  "success": true,
  "metric": "api_calls",
  "count": 1
}