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

​
Route structure

The Metabind API uses two route prefixes that determine which authentication method to use: All endpoints are available via /app/v1/ with JWT authentication. Some endpoints are also available via /api/v1/ with API key authentication, mostly for reading published content.

​
Bearer token authentication

For administrative operations and full API access, use JWT bearer tokens with the Admin API (/app/v1/ routes).

​
Obtaining a JWT token

JWT tokens are obtained by signing in to Metabind Studio. After authentication, your session provides the JWT tokens used for API requests. For programmatic access to admin operations:
  1. Sign in to Metabind Studio.
  2. Use browser developer tools to inspect the Authorization header in API requests.
  3. Copy the bearer token for use in your scripts or tools.
JWT tokens expire periodically. For long-running integrations that need admin access, create a dedicated user with an appropriately scoped role and refresh its JWT through the standard sign-in flow. There is no separate “service account” entity today — the convention is to provision a user that exists for automation only.

​
Using bearer tokens

Include the JWT in the Authorization header:
Example request:

​
API key authentication

For client applications consuming published content, use API key authentication with the Client API (/api/v1/ routes). This is the recommended approach for mobile apps, web frontends, and other client-side integrations.
When building client applications (iOS, Android, React, web), use the /api/v1/ routes with API keys. Reserve /app/v1/ routes for admin tools and integrations that require full access.

​
REST client API

Include the API key in the x-api-key header:

​
GraphQL API

For the GraphQL API, use the x-api-key header with the value <orgId>:<projectId>:<apiKey>:

​
WebSocket subscriptions

For real-time subscriptions, include the API key in the connection parameters, in the same <orgId>:<projectId>:<apiKey> format:

​
Obtaining API keys

API keys are created and managed in Metabind Studio:
  1. Click the gear icon at the top right (Project Settings), and choose API Keys.
  2. Click +, enter a Name, and click Create.
  3. Copy the generated key — it won’t be shown again.
Keys created in Studio have no scopes. To create a scoped key, use the Create API Key endpoint with scopes, or metabind api-key create --name <name> --scopes '["read:content"]'.
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 access

An API key works only within its project. What it can do there depends on its scopes:
  • An unscoped key, such as any key created in Studio, has full access within the project.
  • A scoped key can do only what its scopes allow, and gets 403 INSUFFICIENT_SCOPE otherwise. See Scopes.
A key that ships inside a client app can be extracted from it, so give client keys only the read scopes they need. For administrative operations, use bearer token authentication with appropriate user permissions.

​
Client API endpoints

The following endpoints are available via /api/v1/ with API key authentication. They return published content only, except packages/draft and types requests with draft=true, which return drafts. For practical code examples using these endpoints, see Using API keys.

​
Content discovery

GET /api/v1/organizations/{organizationId}/projects/{projectId}/saved-searches
GET /api/v1/organizations/{organizationId}/projects/{projectId}/saved-searches/{savedSearchId}
POST /api/v1/organizations/{organizationId}/projects/{projectId}/saved-searches/{savedSearchId}/execute
GET /api/v1/organizations/{organizationId}/projects/{projectId}/tags
GET /api/v1/organizations/{organizationId}/projects/{projectId}/tags/{tagId}
GET /api/v1/organizations/{organizationId}/projects/{projectId}/types
GET /api/v1/organizations/{organizationId}/projects/{projectId}/types/{contentTypeId}
GET /api/v1/organizations/{organizationId}/projects/{projectId}/types/{contentTypeId}/versions

​
Content access

GET /api/v1/organizations/{organizationId}/projects/{projectId}/components
GET /api/v1/organizations/{organizationId}/projects/{projectId}/components/{componentId}
GET /api/v1/organizations/{organizationId}/projects/{projectId}/packages
GET /api/v1/organizations/{organizationId}/projects/{projectId}/packages/draft
GET /api/v1/organizations/{organizationId}/projects/{projectId}/packages/{version}/resolved
GET /api/v1/organizations/{organizationId}/projects/{projectId}/content
GET /api/v1/organizations/{organizationId}/projects/{projectId}/content/{contentId}/resolved
GET /api/v1/organizations/{organizationId}/projects/{projectId}/assets

​
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.
Delete API keys that are no longer in use to reduce your attack surface.