Admin API Documentation

INTRODUCTION

AUTHENTICATION

API KEYS

M2M MACHINES

Getting Started

The Admin API provides programmatic access to manage your organization's authentication credentials, API keys, and M2M tokens. Use this API to automate key rotation, manage access, and integrate with your deployment pipelines.

Base URL

https://admin.relativity6.com

Non-prod (dev/staging):

https://admin-dev.relativity6.com

Authentication

Admin API endpoints (except /oauth/token) require a valid Bearer token from an authenticated admin user.

Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Admin tokens are obtained through your organization's identity provider (Clerk).

OAuth Token Endpoint

POST

/oauth/token

Exchange machine credentials for an OAuth 2.0 access token using the Client Credentials flow. This endpoint is used for machine-to-machine (M2M) authentication and does not require prior authentication.

No Authentication Required

This endpoint does not require prior authentication. The client_secret serves as the authentication credential.

Request Example

POST https://admin.relativity6.com/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "mch_your_machine_id",
  "client_secret": "ak_your_machine_secret"
}

Request Parameters

Parameter	Type	Required	Description
grant_type	string	Yes	Must be `client_credentials`
client_id	string	Yes	Your machine identifier (starts with `mch_`)
client_secret	string	Yes	Your machine secret key (starts with `ak_`)

Response

{
  "access_token": "mt_CZDQ5VA9232MHSNT1AXN2XCZ25FNM501",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "marvin2-api platform-api"
}

Response Properties

Property	Type	Description
access_token	string	The M2M access token (starts with `mt_`)
token_type	string	Always `Bearer`
expires_in	number	Token validity in seconds (typically 3600 = 1 hour)
scope	string	Space-separated list of APIs this token can access

Error Codes

Status	Description
400	Bad Request - Unsupported grant type or missing parameters
401	Unauthorized - Invalid client_id or client_secret
500	Server Error - Token generation failed

API Key Management

The API Key endpoints allow you to programmatically create, list, rotate, and delete API keys for your organization. All endpoints require admin authentication.

Admin Authentication Required

All API key management endpoints require a valid admin JWT token in the Authorization header.

List Keys

Retrieve all API keys for an organization

GET /organizations/{orgId}/api-keys

Create Key

Generate a new API key

POST /organizations/{orgId}/api-keys

Get Key

Get details for a specific API key

GET /organizations/{orgId}/api-keys/{keyId}

Reveal Secret

Reveal the full API key secret

GET /organizations/{orgId}/api-keys/{keyId}/secret

Rotate Key

Generate a new secret for an existing key

POST /organizations/{orgId}/api-keys/{keyId}/rotate

Delete Key

Permanently revoke an API key

DELETE /organizations/{orgId}/api-keys/{keyId}

GET

/organizations/{orgId}/api-keys

Retrieve all API keys associated with an organization. Returns key metadata but not the full secret.

Request Example

GET https://admin.relativity6.com/organizations/org_abc123/api-keys
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "displayHint": "r6-key...xyz",
      "status": "active",
      "productId": "marvin2-api",
      "createdAt": 1699574400000,
      "lastUsed": 1699660800000,
      "canReveal": true
    },
    {
      "id": "key_def456",
      "name": "Staging API Key",
      "displayHint": "r6-key...abc",
      "status": "active",
      "productId": "platform-api",
      "createdAt": 1699488000000,
      "lastUsed": null,
      "canReveal": true
    }
  ]
}

POST

/organizations/{orgId}/api-keys

Create a new API key for an organization. The full key is only returned once at creation time.

Request Example

POST https://admin.relativity6.com/organizations/org_abc123/api-keys
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN
Content-Type: application/json

{
  "name": "New Production Key",
  "productId": "marvin2-api"
}

Request Parameters

Parameter	Type	Required	Description
name	string	Yes	A descriptive name for the API key
productId	string	Yes	The product this key is for (`marvin2-api`, `platform-api`)

Response

{
  "id": "key_xyz789",
  "name": "New Production Key",
  "displayHint": "r6-key...def",
  "fullKey": "r6-key_xyz789.abcdef123456789",
  "status": "active",
  "productId": "marvin2-api",
  "createdAt": 1699747200000,
  "canReveal": true
}

Save the Full Key

The fullKey is only returned once at creation. Store it securely - you can use the reveal endpoint later, but best practice is to save it immediately.

GET

/organizations/{orgId}/api-keys/{keyId}

Retrieve details for a specific API key. Does not include the full secret.

Request Example

GET https://admin.relativity6.com/organizations/org_abc123/api-keys/key_xyz789
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

{
  "id": "key_xyz789",
  "name": "New Production Key",
  "displayHint": "r6-key...def",
  "status": "active",
  "productId": "marvin2-api",
  "createdAt": 1699747200000,
  "lastUsed": 1699833600000,
  "canReveal": true
}

GET

/organizations/{orgId}/api-keys/{keyId}/secret

Reveal the full API key secret. This is useful if you need to retrieve a key that was created earlier.

Request Example

GET https://admin.relativity6.com/organizations/org_abc123/api-keys/key_xyz789/secret
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

{
  "keyId": "key_xyz789",
  "fullKey": "r6-key_xyz789.abcdef123456789"
}

POST

/organizations/{orgId}/api-keys/{keyId}/rotate

Generate a new secret for an existing API key. The old secret is immediately invalidated. The new full key is returned in the response.

Request Example

POST https://admin.relativity6.com/organizations/org_abc123/api-keys/key_xyz789/rotate
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

{
  "id": "key_xyz789",
  "name": "New Production Key",
  "displayHint": "r6-key...ghi",
  "fullKey": "r6-key_xyz789.newSecret987654321",
  "status": "active",
  "productId": "marvin2-api",
  "rotatedAt": 1699920000000
}

Immediate Invalidation

The old secret is invalidated immediately upon rotation. Ensure you update all systems using this key before rotating, or be prepared to handle authentication failures briefly.

DELETE

/organizations/{orgId}/api-keys/{keyId}

Permanently revoke and delete an API key. This action cannot be undone.

Request Example

DELETE https://admin.relativity6.com/organizations/org_abc123/api-keys/key_xyz789
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

HTTP 204 No Content

Error Codes

Status	Description
400	Bad Request - Missing required parameters (name, productId)
401	Unauthorized - Missing or invalid Authorization header
403	Forbidden - Insufficient permissions to manage keys for this organization
404	Not Found - Organization or API key does not exist
409	Conflict - Cannot reveal secret (key may have been rotated externally)
500	Server Error - Internal error during key operation

M2M Machine Management

M2M (Machine-to-Machine) machines represent service accounts that can authenticate using the OAuth 2.0 Client Credentials flow. Each machine belongs to an organization and can be granted access to specific APIs.

Machine Authentication Flow

Machines use their client_id (machine ID) and client_secret to obtain short-lived access tokens via the /oauth/token endpoint.

List Machines

Get all machines for an organization

GET /organizations/{orgId}/machines

Create Machine

Provision a new M2M machine

POST /organizations/{orgId}/machines

Get Machine

Get details for a specific machine

GET /organizations/{orgId}/machines/{machineId}

Rotate Secret

Generate a new client secret

POST /organizations/{orgId}/machines/{machineId}/rotate

Delete Machine

Permanently delete a machine

DELETE /organizations/{orgId}/machines/{machineId}

GET

/organizations/{orgId}/machines

Retrieve all M2M machines for an organization.

Request Example

GET https://admin.relativity6.com/organizations/org_abc123/machines
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

{
  "machines": [
    {
      "id": "uuid-1234-5678",
      "machineId": "mch_abc123xyz",
      "organizationId": "org_abc123",
      "name": "Production Backend Service",
      "description": "Main backend service for automated data processing",
      "status": "active",
      "scopes": ["marvin2-api", "platform-api"],
      "createdAt": 1699574400000,
      "createdBy": "user_admin123",
      "updatedAt": 1699660800000
    },
    {
      "id": "uuid-9012-3456",
      "machineId": "mch_def456uvw",
      "organizationId": "org_abc123",
      "name": "Staging Integration",
      "status": "active",
      "scopes": ["marvin2-api"],
      "createdAt": 1699488000000,
      "updatedAt": 1699488000000
    }
  ]
}

POST

/organizations/{orgId}/machines

Create a new M2M machine for an organization. The machine secret is only returned once at creation time.

Request Example

POST https://admin.relativity6.com/organizations/org_abc123/machines
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN
Content-Type: application/json

{
  "name": "Production Backend Service",
  "description": "Main backend service for automated data processing",
  "scopes": ["marvin2-api", "platform-api"]
}

Request Parameters

Parameter	Type	Required	Description
name	string	Yes	A descriptive name for the machine
description	string	No	Optional description of the machine's purpose
scopes	array	No	Array of product IDs this machine can access (e.g., `["marvin2-api", "platform-api"]`)

Response

{
  "id": "uuid-7890-1234",
  "machineId": "mch_ghi789rst",
  "organizationId": "org_abc123",
  "name": "Production Backend Service",
  "description": "Main backend service for automated data processing",
  "status": "active",
  "scopes": ["marvin2-api", "platform-api"],
  "createdAt": 1699747200000,
  "createdBy": "user_admin123",
  "updatedAt": 1699747200000,
  "secret": "ak_NEWMACHINESECRET123456789"
}

Save the Machine Secret

The secret is only returned once at creation. Store it securely - if lost, you must rotate the secret to get a new one.

GET

/organizations/{orgId}/machines/{machineId}

Retrieve details for a specific M2M machine. Does not include the secret.

Request Example

GET https://admin.relativity6.com/organizations/org_abc123/machines/mch_ghi789rst
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

{
  "id": "uuid-7890-1234",
  "machineId": "mch_ghi789rst",
  "organizationId": "org_abc123",
  "name": "Production Backend Service",
  "description": "Main backend service for automated data processing",
  "status": "active",
  "scopes": ["marvin2-api", "platform-api"],
  "createdAt": 1699747200000,
  "createdBy": "user_admin123",
  "updatedAt": 1699920000000
}

POST

/organizations/{orgId}/machines/{machineId}/rotate

Generate a new secret for an existing M2M machine. The old secret will be invalidated after a brief grace period (typically 1 second).

Request Example

POST https://admin.relativity6.com/organizations/org_abc123/machines/mch_ghi789rst/rotate
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

{
  "id": "uuid-7890-1234",
  "machineId": "mch_ghi789rst",
  "organizationId": "org_abc123",
  "name": "Production Backend Service",
  "description": "Main backend service for automated data processing",
  "status": "active",
  "scopes": ["marvin2-api", "platform-api"],
  "createdAt": 1699747200000,
  "createdBy": "user_admin123",
  "updatedAt": 1699920000000,
  "secret": "ak_ROTATEDNEWSECRET987654321"
}

Secret Rotation

Existing tokens issued with the old secret remain valid until they expire. However, new token requests using the old secret will fail immediately. Update your systems with the new secret promptly.

DELETE

/organizations/{orgId}/machines/{machineId}

Permanently delete an M2M machine. All tokens issued for this machine will be immediately invalidated.

Request Example

DELETE https://admin.relativity6.com/organizations/org_abc123/machines/mch_ghi789rst
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN

Response

HTTP 204 No Content

Error Codes

Status	Description
400	Bad Request - Missing required parameters (name)
401	Unauthorized - Missing or invalid Authorization header
403	Forbidden - Insufficient permissions to manage machines for this organization
404	Not Found - Organization or machine does not exist
422	Unprocessable Entity - Failed to create/rotate machine in identity provider
500	Server Error - Internal error during machine operation