Skip to main content
These endpoints are used by the admin interface to manage API keys for services. All endpoints require admin authentication.

​
Create API Key

POST /service/{service_id}/api-key Create a new API key for a service.

​
Path Parameters

ParameterTypeDescription
service_iduuidThe service ID

​
Request Body

{
  "name": "Production API Key",
  "key_type": "normal",
  "created_by": "user-uuid"
}

​
Key Types

TypeDescription
normalProduction API key with full permissions
teamTeam API key that can only send to team members and guest list
testTest API key that simulates sending without actually delivering notifications

​
Response

{
  "data": "service-uuid-is6av-26k5-2907-dba1-d2e4a3f9cd58-f7f86e61-d6de-4241-a298-4cfc4bd43579"
}
Status Code: 201 Created
The full API key is only returned once at creation time. Store it securely - it cannot be retrieved later.

​
Get API Keys

GET /service/{service_id}/api-keys Retrieve all API keys for a service.

​
Path Parameters

ParameterTypeDescription
service_iduuidThe service ID

​
Response

{
  "apiKeys": [
    {
      "id": "key-uuid",
      "name": "Production API Key",
      "service_id": "service-uuid",
      "key_type": "normal",
      "expiry_date": null,
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": {
        "id": "user-uuid",
        "name": "Admin User"
      },
      "version": 1
    },
    {
      "id": "key-uuid-2",
      "name": "Test API Key",
      "service_id": "service-uuid",
      "key_type": "test",
      "expiry_date": null,
      "created_at": "2023-01-02T00:00:00Z",
      "created_by": {
        "id": "user-uuid",
        "name": "Admin User"
      },
      "version": 1
    }
  ]
}

​
Get API Key by ID

GET /service/{service_id}/api-keys/{key_id} Retrieve a specific API key.

​
Path Parameters

ParameterTypeDescription
service_iduuidThe service ID
key_iduuidThe API key ID

​
Response

{
  "apiKeys": [
    {
      "id": "key-uuid",
      "name": "Production API Key",
      "service_id": "service-uuid",
      "key_type": "normal",
      "expiry_date": null,
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": {
        "id": "user-uuid",
        "name": "Admin User"
      },
      "version": 1
    }
  ]
}

​
Revoke API Key

POST /service/{service_id}/api-key/revoke/{api_key_id} Revoke an API key. This sets an expiry date on the key, preventing it from being used for new requests.

​
Path Parameters

ParameterTypeDescription
service_iduuidThe service ID
api_key_iduuidThe API key ID to revoke

​
Response

Status Code: 202 Accepted
Revoking an API key does not delete it - it sets an expiry date to prevent future use. The key will still appear in the API key list but with an expiry date set.

​
API Key Format

API keys follow this format: 
{service_id}-{uuid1}-{uuid2}
Example: 
service-abc123-def456-789ghi-012jkl-345mno-pqr678
The key contains:
  • Service ID - Identifies which service the key belongs to
  • UUID1 - The actual API key ID in the database
  • UUID2 - A secret value used for authentication

​
API Key Validation

When making requests to the public API, include the API key in the Authorization header: 
Authorization: ApiKey-v1 {your-api-key}
The system validates:
  1. The key format is correct
  2. The service ID in the key matches an existing service
  3. The API key exists and belongs to that service
  4. The key has not expired
  5. The secret portion matches what’s stored

​
Key Types in Detail

​
Normal Keys

Normal keys have full permissions to:
  • Send notifications to any recipient
  • Use all notification types (email, SMS, letter) if service has permissions
  • Access all public API endpoints
  • No rate limiting beyond standard service limits

​
Team Keys

Team keys are restricted to:
  • Sending only to team members (users in the service)
  • Sending to guest list recipients (for trial services)
  • Cannot send to general public
  • Useful for testing and development

​
Test Keys

Test keys:
  • Simulate sending without actually delivering notifications
  • Useful for integration testing
  • Create notification records but don’t send to providers
  • Don’t count against service limits
  • Validate templates and recipient formats

​
Best Practices

Rotate Keys Regularly

Create new keys and revoke old ones periodically for security

Use Descriptive Names

Name keys based on their purpose or application (e.g., “Production Web App”, “Staging Environment”)

Separate Environments

Use different keys for development, staging, and production

Monitor Usage

Review which keys are actively used and revoke unused keys
See also:

Build docs developers (and LLMs) love

Get started for freeTalk to us