Authentication

Minds research API requests require an API key or an approved OAuth grant. Public pages and discovery documents can be read without signing in.

Getting Your API Key

1. Log in to your Minds account
2. Navigate to Settings → API Keys
3. Click Generate New API Key
4. Copy your API key immediately (you won't be able to see it again!)

API keys are prefixed with minds_ and look like this: minds_0000111122223333444455556666777788889999aaaabbbb

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer minds_your_api_key_here

Example Request

curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer minds_your_api_key"

Security Best Practices

Keep Your Keys Secret

• Never commit API keys to version control
• Never share keys in public forums or chat
• Store keys in environment variables or secure vaults
• Rotate keys regularly for security

Use Environment Variables

# Set your key as an environment variable
export MINDS_API_KEY="minds_your_api_key_here"

# Use it in requests
curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer $MINDS_API_KEY"

Rotate Keys Regularly

If you suspect a key has been compromised:

1. Generate a new API key
2. Update your applications to use the new key
3. Delete the old key

Identifying the Authenticated User

Verify that an API key is valid and identify which account it belongs to:

GET /api/v1/auth/me

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Returns the user ID associated with the API key. Useful for confirming credentials at startup or after rotating keys. Returns 401 Unauthorized if the key is missing or invalid.

Managing API Keys

List Your API Keys

GET /api/v1/api-keys

Returns a list of your API keys with metadata (the actual key values are never returned):

[
  {
    "id": "key-id",
    "name": "prod",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "lastUsedAt": "2025-12-10T13:00:00.000Z"
  }
]

Create a New API Key

POST /api/v1/api-keys

Headers:

Content-Type: application/json

Request Body (optional):

{
  "name": "prod"
}

The optional name field is a human-readable label for the key (string, 1–100 chars). It helps you identify keys in the list endpoint and in the Settings UI. Whitespace is trimmed; an empty or missing value is stored as null. An empty request body is still accepted and creates an unnamed key.

Response includes the actual key (only time you'll see it):

{
  "id": "new-key-id",
  "name": "prod",
  "key": "minds_0000111122223333444455556666777788889999aaaabbbb",
  "createdAt": "2025-12-10T12:00:00.000Z"
}

Example with name

curl -X POST "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod"}'

⚠️ Important: Save the key value immediately! You won't be able to retrieve it again.

Delete an API Key

DELETE /api/v1/api-keys/{keyId}

Returns 204 No Content with an empty body on success.

Authentication Errors

401 Unauthorized

Your API key is missing or invalid.

{
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Unauthorized",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "expectedNoise": true
  }
}

Every rejected credential returns the same generic Unauthorized message — the API deliberately does not distinguish a missing key from an invalid or revoked one. The data.expectedNoise flag is internal telemetry metadata and not part of the contract.

Solutions:

• Check that you've included the Authorization header
• Verify your API key is correct
• Ensure you're using the Bearer prefix
• Generate a new key if the old one was deleted

Plan-Based Access

API access is a supported paid-plan capability and remains subject to the resource, response, and workspace allowances shown in the product or agreed in the customer's contract. Do not hard-code public pricing or allowances into an integration; handle structured PLAN_LIMIT / plan_limited responses and inspect the authenticated plan context. The Starter plan appears as "premium" in API payloads.

View Plans

Read-only agent connections

An agent can request read access through auth.md. Sign in to the intended verified account, enter the six-digit code shown by your agent, and approve the displayed scopes. The request expires after ten minutes.

The initial registration credential can only check its own status. After approval, the agent receives a scoped OAuth token for supported Mind, Audience, and Study reads. It cannot change research, start paid work, create API keys, or manage your account. Remove the OAuth connection in Settings to revoke access.

For MCP, use the protected resource metadata. Public-page metadata has an empty scopes list because reading those pages does not require authentication.