Skip to content
For developers

API Keys API

REST endpoints for api keys — request and response reference with examples.

Last updated

Create and revoke API keys programmatically, or self-serve in the app: Settings → API Keys → Create API Key.

Base URL: https://api.actuallycare.com/v1 · Errors use the standard envelope — see Errors.

List API keys#

GET/v1/api-keys

Returns list of API keys for authenticated user (keys are masked)

Responses#

StatusMeaningWhat to do
200API keys retrieved successfully
401UnauthorizedSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl "https://api.actuallycare.com/v1/api-keys" \
  -H "Authorization: Bearer YOUR_JWT"

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

This endpoint takes a JWT, not an API key. How to get one.
GET /v1/api-keys

Enter a token to send.

Example response (200)#

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jordan Lee",
      "key_preview": "example key preview",
      "is_active": true,
      "created_at": "2026-07-15T14:32:10.000Z",
      "last_used_at": "2026-07-15T14:32:10.000Z",
      "expires_at": "2026-07-15T14:32:10.000Z"
    }
  ]
}

Create new API key#

POST/v1/api-keys

Generates a new API key for authenticated user. Key is only shown once.

⚠️ CONSEQUENTIAL ACTION: Creates new authentication credentials. Store the key securely - it cannot be retrieved again.

Request body#

FieldTypeRequiredDescription
namestringYesDescriptive name for the API key
expiresInDaysintegerNoNumber of days until expiration (1-365). If omitted, the key does not expire.
scopesobjectYesMap of resource → allowed actions (an OBJECT, not a string array), e.g. {"escrows": ["read", "write"], "clients": ["read"]}. Use resource "all" as a wildcard (e.g. {"all": ["read"]}). Valid resources: all, appointments, artifacts, clients, contacts, daily-insights, deals, details, disclosures, documents, emails, engagements, entity-links, escrows, groups, habits, integrations, inventory, leads, listings, mls-agents, notifications, onboarding, open-houses, organizations, partners, pipelines, prospects, referral-pipeline, referrals, saved-searches, search, security, service-types, showings, tasks, tracks, users, verified-sales (source of truth: KNOWN_RESOURCES in middleware/auth/apiKeyScope.js). Required (SPEC-5781). A request with no scopes, {}, an unknown resource or an unknown action is rejected with 400. An endpoint that is not mapped to a resource denies every API key (403).

Responses#

StatusMeaningWhat to do
201API key created successfully
400Validation errorFix the request; error.message and error.details name the problem. Don't retry unchanged
401UnauthorizedSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X POST "https://api.actuallycare.com/v1/api-keys" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan Lee",
    "scopes": {
      "all": [
        "read"
      ],
      "escrows": [
        "read",
        "write"
      ]
    }
  }'

Example response (201)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "example key",
    "name": "Jordan Lee",
    "key_prefix": "example key prefix",
    "scopes": {},
    "expires_at": "2026-07-15T14:32:10.000Z",
    "created_at": "2026-07-15T14:32:10.000Z"
  },
  "message": "example message",
  "timestamp": "2026-07-15T14:32:10.000Z"
}

Update API key scopes#

PATCH/v1/api-keys/{id}/scopes

Replaces the scopes object on an existing API key. Requires JWT authentication (API keys cannot manage API keys). Scopes are a map of resource → allowed actions; see POST /api-keys for the valid resource list.

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesFormat: uuid

Request body#

FieldTypeRequiredDescription
scopesobjectYesFull replacement scopes map (resource → actions)

Responses#

StatusMeaningWhat to do
200Scopes updated
400Validation error (scopes must be an object)Fix the request; error.message and error.details name the problem. Don't retry unchanged
401UnauthorizedSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
404API key not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X PATCH "https://api.actuallycare.com/v1/api-keys/:id/scopes" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": {
      "escrows": [
        "read",
        "write"
      ],
      "all": [
        "read"
      ]
    }
  }'

Example response (200)#

{
  "success": true,
  "data": {
    "id": "7d3f9b2e-5a8c-4e1d-b6f0-9c2a4e8d1b57",
    "scopes": {
      "escrows": [
        "read",
        "write"
      ],
      "all": [
        "read"
      ]
    }
  },
  "timestamp": "2026-07-01T22:48:31.554Z"
}

Revoke API key#

PUT/v1/api-keys/{id}/revoke

Deactivates an API key without deleting it

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesFormat: uuid

Responses#

StatusMeaningWhat to do
200API key revoked successfully
401UnauthorizedSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
404API key not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X PUT "https://api.actuallycare.com/v1/api-keys/:id/revoke" \
  -H "Authorization: Bearer YOUR_JWT"

Example response (200)#

{
  "success": true,
  "data": {
    "id": "7d3f9b2e-5a8c-4e1d-b6f0-9c2a4e8d1b57"
  },
  "timestamp": "2026-07-01T22:53:07.114Z"
}

Delete API key#

DELETE/v1/api-keys/{id}

Permanently deletes an API key

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesFormat: uuid

Responses#

StatusMeaningWhat to do
200API key deleted successfully
401UnauthorizedSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
404API key not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X DELETE "https://api.actuallycare.com/v1/api-keys/:id" \
  -H "Authorization: Bearer YOUR_JWT"

Example response (200)#

{
  "success": true,
  "data": {},
  "timestamp": "2026-07-15T14:32:10.000Z"
}