API Keys

API Keys provide a simple authentication mechanism for third-party integrations and automated systems that need to interact with the GxP API.

Overview

API Keys are different from Sanctum tokens in several ways:

Feature	API Keys	Sanctum Tokens
User association	Team-level	User-level
Expiration	Configurable	Optional
Rotation	Automatic support	Manual
Use case	Server-to-server	User applications

Creating API Keys

Via Dashboard

1. Log in to the GxP Dashboard as a Team Administrator
2. Navigate to Team Settings > API Keys
3. Click Create API Key
4. Configure:
   • Name: Descriptive name for the key
   • Permissions: Select allowed operations
   • IP Allowlist: Optionally restrict to specific IPs
   • Expiration: Set expiration date (optional)
5. Click Create
6. Copy and securely store the key (shown only once)

Using API Keys

Include the API key in the X-API-Key header:

curl -X GET "https://api.gramercy.cloud/api/v1/projects/my-team/my-project/attendees" \
  -H "X-API-Key: gxp_live_abc123..." \
  -H "Accept: application/json"

Key Format

GxP API keys follow a predictable format:

gxp_{environment}_{random_string}

• gxp_live_* - Production keys
• gxp_test_* - Test/sandbox keys

Key Permissions

When creating an API key, you can scope it to specific resources and operations:

Resource Permissions

{
  "attendees": ["read", "write", "delete"],
  "forms": ["read"],
  "access_points": ["read", "write"],
  "webhooks": ["read", "write"]
}

Project Scoping

Keys can be scoped to specific projects:

{
  "projects": ["project-slug-1", "project-slug-2"],
  "permissions": {
    "attendees": ["read", "write"]
  }
}

IP Allowlisting

For enhanced security, restrict API key usage to specific IP addresses:

{
  "allowed_ips": [
    "192.168.1.100",
    "10.0.0.0/24"
  ]
}

Requests from non-allowlisted IPs will receive a 403 Forbidden response.

Key Rotation

GxP supports seamless key rotation to maintain security:

Manual Rotation

1. Create a new API key with the same permissions
2. Update your application to use the new key
3. Revoke the old key once migration is complete

Automatic Rotation

Configure automatic rotation in the dashboard:

1. Navigate to Team Settings > API Keys
2. Select the key to configure
3. Enable Auto-Rotation
4. Set rotation interval (30, 60, or 90 days)

When auto-rotation is enabled:

• A new key is generated before the old one expires
• Both keys work during a 24-hour overlap period
• Webhook notifications are sent for key rotations

Monitoring Key Usage

Track API key usage in the dashboard:

• Request count: Total requests made
• Last used: Timestamp of last request
• Error rate: Percentage of failed requests
• Endpoints hit: Most frequently accessed endpoints

Revoking Keys

To revoke an API key:

Via Dashboard

1. Navigate to Team Settings > API Keys
2. Find the key to revoke
3. Click Revoke
4. Confirm the action

Via API

curl -X DELETE "https://api.gramercy.cloud/api/v1/api-keys/KEY_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Accept: application/json"

Best Practices

1. Use descriptive names: Name keys after their purpose (e.g., "Registration Kiosk", "CRM Sync")

2. Minimize permissions: Only grant the permissions each integration needs

3. Set expiration dates: For temporary integrations, set appropriate expiration

4. Use IP allowlisting: When possible, restrict keys to known IP addresses

5. Monitor usage: Regularly review key usage and revoke unused keys

6. Rotate regularly: Even without auto-rotation, rotate keys periodically

7. Never share keys: Each integration should have its own key

Error Responses

Invalid Key (401)

{
  "message": "Invalid API key."
}

Expired Key (401)

{
  "message": "API key has expired."
}

IP Not Allowed (403)

{
  "message": "Request IP not in allowlist.",
  "ip": "203.0.113.50"
}

Insufficient Permissions (403)

{
  "message": "API key lacks required permission.",
  "required": "attendees:write"
}