Skip to main content
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

ScopeAccess
read:charge_pointsRead charge point data and status
write:charge_pointsRegister and update charge points
read:billingView billing records and invoices
write:billingModify billing configuration
read:analyticsAccess usage analytics and reports
write:webhooksCreate and manage webhook endpoints
read:sessionsView 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 -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"
  }
}
StatusCodeMeaning
400invalid_scopeOne or more scopes are not recognized
400name_takenA key with this name already exists in your organization
401unauthorizedMissing or invalid API key on the request itself
403forbiddenYour key lacks the required scope for this operation
404not_foundThe specified key_id does not exist
429rate_limitedToo many requests — back off and retry