Authentication

All Minds API requests require authentication using API keys. API keys are unique to your account and provide secure access to your resources.

Getting Your API Key

Log in to your Minds account
Navigate to Settings → API Keys
Click Generate New API Key
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_10e9d89a4f88331be68ce05736271bcc58409a26b03a412b

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:

Generate a new API key
Update your applications to use the new key
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_10e9d89a4f88331be68ce05736271bcc58409a26b03a412b",
  "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": "Invalid or missing API key"
}

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 available to all users. However, free plan users have limited capabilities:

Free: 1 mind, no flows
Lite: 3 minds, 3 flows
Premium/Academic/Team: Unlimited minds and flows

View Plans

Authentication

User Access