Skip to main content

​
Authentication

All Metabind API requests require authentication. The platform supports two authentication methods depending on your use case.

​
API Key Authentication

For server-to-server communication and client applications consuming published content, use API key authentication.

​
REST API

Include the API key in the Authorization header with a Bearer prefix: 
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

​
GraphQL API

For the GraphQL API, use the x-api-key header: 
headers: {
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

​
WebSocket Subscriptions

For real-time subscriptions, include the API key in the connection parameters: 
connectionParams: {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
}

​
Bearer Token Authentication

For user-authenticated requests (typically from the CMS frontend), use JWT bearer tokens obtained through the authentication flow. 
headers: {
  'Authorization': 'Bearer YOUR_JWT_TOKEN',
  'Content-Type': 'application/json'
}

​
Obtaining API Keys

API keys are created and managed through the Metabind CMS:
  1. Navigate to your project settings
  2. Go to the API Keys section
  3. Click Create API Key
  4. Provide a name and optional description
  5. Copy the generated key (it won’t be shown again)
API keys are displayed only once when created. Store them securely. If you lose an API key, you’ll need to create a new one.

​
API Key Permissions

API keys inherit permissions from the project they belong to. By default, API keys have read-only access to published content.
PermissionDescription
content.readRead published content
packages.readRead published packages
assets.readRead active assets
For administrative operations (create, update, delete), use bearer token authentication with appropriate user permissions.

​
Request Examples

​
cURL

curl -X GET "https://api.metabind.ai/v1/organizations/org123/projects/proj456/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
JavaScript (Fetch)

const response = await fetch(
  'https://api.metabind.ai/v1/organizations/org123/projects/proj456/content',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

​
JavaScript (GraphQL)

const response = await fetch('https://api.metabind.ai/graphql', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `
      query GetContent($id: ID!) {
        content(id: $id) {
          id
          name
          compiled
        }
      }
    `,
    variables: { id: 'content123' }
  })
});

​
Security Best Practices

API keys should be kept on the server side. For mobile apps, use a backend proxy or the GraphQL API with appropriate rate limiting.
Create separate API keys for development, staging, and production environments.
Periodically revoke old API keys and create new ones, especially if you suspect a key may have been compromised.
Request only the permissions your application needs. Most client applications only need read access to published content.

​
Error Responses

Authentication failures return appropriate HTTP status codes:
StatusDescription
401 UnauthorizedMissing or invalid API key/token
403 ForbiddenValid authentication but insufficient permissions
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}