API Keys — Create, Scope, and Revoke Access Tokens

Create, list, and revoke scoped API keys for your Dynamo CSMS organization. Control access to charge points, billing, analytics, and webhook endpoints.

Dynamo CSMS authenticates requests using API keys tied to your organization. You can create multiple keys with distinct permission scopes and revoke them independently. All requests must include your key in either the Authorization header or the X-API-Key header.

# Option A — Bearer token
Authorization: Bearer YOUR_API_KEY

# Option B — direct header
X-API-Key: YOUR_API_KEY

Available scopes

Scope	Access
read:charge_points	Read charge point data and status
write:charge_points	Register and update charge points
read:billing	View billing records and invoices
write:billing	Modify billing configuration
read:analytics	Access usage analytics and reports
write:webhooks	Create and manage webhook endpoints
read:sessions	View charging session history

---

List API keys

GET /api/v1/org/api-keys

Returns all API keys created for your organization, including their scopes and last-used timestamps. Secret key values are never returned after initial creation.

curl https://api.dynamo-csms.com/api/v1/org/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production Dashboard",
      "scopes": ["read:charge_points", "read:billing", "read:sessions"],
      "created_at": "2024-01-15T10:00:00Z",
      "last_used_at": "2024-01-20T14:30:00Z",
      "expires_at": null
    },
    {
      "id": "key_def456",
      "name": "Analytics Exporter",
      "scopes": ["read:analytics"],
      "created_at": "2024-02-01T08:00:00Z",
      "last_used_at": null,
      "expires_at": "2025-02-01T08:00:00Z"
    }
  ],
  "total": 2
}

keys · array

Array of API key objects belonging to your organization.

keys[].id · string

Unique identifier for the key. Use this ID when revoking the key.

keys[].name · string

Human-readable label you assigned when creating the key.

keys[].scopes · string[]

List of permission scopes granted to this key.

keys[].created_at · string

ISO 8601 timestamp of when the key was created.

keys[].last_used_at · string | null

ISO 8601 timestamp of the most recent authenticated request. null if the key has never been used.

keys[].expires_at · string | null

ISO 8601 expiry timestamp. null for keys with no expiration.

total · integer

Total number of keys in your organization.

---

Create API key

POST /api/v1/org/api-keys

Creates a new API key. The secret key value is returned only once in the creation response — store it securely immediately. Subsequent calls to list keys will not return the secret value.

name · string · required

A human-readable label for this key (e.g. "Production Dashboard", "CI Pipeline"). Must be unique within your organization. Maximum 128 characters.

scopes · string[] · required

List of permission scopes to grant. Must contain at least one scope. See the scopes table above for valid values.

expires_in_days · integer

Optional. Number of days until the key expires. Omit for a non-expiring key. Must be between 1 and 3650.

cURL

curl -X POST https://api.dynamo-csms.com/api/v1/org/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fleet Monitor",
    "scopes": ["read:charge_points", "read:sessions", "read:analytics"],
    "expires_in_days": 365
  }'

Response 201 Created

{
  "id": "key_xyz789",
  "name": "Fleet Monitor",
  "key": "dynamo_live_sk_4f8a2b1c9d3e7f0a5b6c8d2e1f4a7b3c",
  "scopes": ["read:charge_points", "read:sessions", "read:analytics"],
  "created_at": "2024-03-10T12:00:00Z",
  "expires_at": "2025-03-10T12:00:00Z"
}

id · string

Unique key identifier. Use this to revoke the key.

name · string

The label you provided.

key · string

The secret API key value. This is the only time this value is returned — save it immediately.

scopes · string[]

Confirmed list of scopes granted to the key.

created_at · string

ISO 8601 creation timestamp.

expires_at · string | null

ISO 8601 expiry timestamp, or null if the key does not expire.

---

Revoke API key

DELETE /api/v1/org/api-keys/{key_id}

Permanently revokes an API key. Any in-flight requests using this key will fail immediately. This action cannot be undone.

key_id · string · required

The id of the key to revoke, as returned by the list or create endpoints.

curl -X DELETE https://api.dynamo-csms.com/api/v1/org/api-keys/key_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 204 No Content

An empty body is returned on success.

---

Error responses

All API key endpoints return standard error objects on failure.

{
  "error": {
    "code": "invalid_scope",
    "message": "Scope 'write:unknown' is not a valid permission scope.",
    "request_id": "req_1a2b3c4d"
  }
}

Status	Code	Meaning
400	invalid_scope	One or more scopes are not recognized
400	name_taken	A key with this name already exists in your organization
401	unauthorized	Missing or invalid API key on the request itself
403	forbidden	Your key lacks the required scope for this operation
404	not_found	The specified key_id does not exist
429	rate_limited	Too many requests — back off and retry