Authentication

How to authenticate with the Maeve Social API

The Maeve Social API accepts Bearer credentials in the Authorization header.

Maeve API key authentication

Use a Maeve API key for servers, scripts, CI jobs, and long-running automation:

curl https://api.maevesocial.com/v1/workspaces \
  -H "Authorization: Bearer $MAEVE_API_KEY"

Treat the raw key as a secret. Do not paste it into shared files, screenshots, logs, or prompts.

Key properties

Property	Description
`name`	A label you assign when creating the key
`keyPrefix`	A visible identifier for recognizing the key later
`workspaceCount`	Number of workspaces the key can access
`workspaces`	Workspace grants attached to the key
`expiresAt`	Optional expiry date. `null` means the key does not expire automatically
`lastUsedAt`	Updated as the key is used

Creating keys

Create API keys from the dashboard at Settings > API Keys. Choose the workspaces the key should access and copy the raw key immediately. It is only shown once.

Keys can also be created programmatically with session authentication. You cannot create a new API key using another API key.

curl -X POST https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/api-keys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD pipeline",
    "workspaceIds": ["WORKSPACE_ID"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

{
  "data": {
    "id": "key-uuid",
    "name": "CI/CD pipeline",
    "key": "raw-key-shown-once",
    "keyPrefix": "visible-prefix",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2027-01-01T00:00:00.000Z"
  },
  "meta": null
}

Important: The raw key value is only returned once at creation time. It is stored as a hash and cannot be retrieved later.

Listing keys

curl https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/api-keys \
  -H "Authorization: Bearer $SESSION_TOKEN"

{
  "data": [
    {
      "id": "key-uuid",
      "name": "CI/CD pipeline",
      "keyPrefix": "visible-prefix",
      "lastUsedAt": "2026-03-15T10:30:00.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "expiresAt": "2027-01-01T00:00:00.000Z",
      "workspaceCount": 1,
      "workspaces": [
        {
          "id": "workspace-uuid",
          "name": "Main Workspace"
        }
      ]
    }
  ],
  "meta": null
}

Revoking keys

Revoke keys from Settings > API Keys, or programmatically:

curl -X DELETE https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/api-keys/KEY_ID \
  -H "Authorization: Bearer $SESSION_TOKEN"

{
  "data": {
    "id": "key-uuid",
    "revoked": true
  },
  "meta": null
}

Revoked keys immediately stop working. The revocation is permanent.

Workspace scoping

Most public API endpoints include the workspace in the path:

/v1/workspaces/{workspaceId}/content
/v1/workspaces/{workspaceId}/media
/v1/workspaces/{workspaceId}/integrations

GET /v1/workspaces is the discovery endpoint and does not take a workspace ID. With API key authentication, it only returns the workspaces granted to that key.

If a key tries to access a workspace outside its grants, the API returns 403 Forbidden.

Session authentication

Session authentication is primarily for first-party use cases, such as dashboard-backed API key management and browser testing. For external services and automation, use a Maeve API key.

PreviousQuickstart NextWorkspaces