Getting Started

Create an API Key

API keys authenticate your requests to Agent-CoreX. Each key starts with acx_ and is stored only as a SHA-256 hash — the raw key is shown exactly once, at creation time.

Last updated: April 2026

Overview

Agent-CoreX API keys are used to authenticate every API request. You can create multiple keys — one per environment, team member, or integration — and revoke any of them individually without affecting the others.

The raw API key is shown only once — at the moment of creation. Copy it before closing the modal. If you lose it, you will need to create a new key.

Create a key

Go to API Keys

In the dashboard sidebar, click API Keys, or navigate directly to /dashboard/keys.

Click 'New key'

Click the "New key" button in the top-right corner of the Keys section. A modal opens with a single text field.

Name your key

Enter a descriptive name for the key. The name helps you identify which key is used where. Examples: Production, Dev, Testing, CI/CD.

The name is only visible to you in the dashboard.

Click 'Create key' and copy immediately

Click "Create key". The modal will show your new key with a green security banner:

Copy this key now — it won't be shown again.

The key is displayed in indigo monospace font. Click the copy icon on the right side of the key field, then click "Done".

Key format & security

Format

All keys start with acx_ followed by 32 random hexadecimal characters, totalling 36 characters.

Example key format

acx_a1b2c3d4e5f6a1b2c3d4e5f6a1bjkbi

Storage

The raw key is never stored. Only a SHA-256 hash and the first 12 characters (prefix, e.g. acx_a1b2c3d4) are saved to the database. The prefix is displayed in the key list so you can identify which key is which.

Authentication caching

When you make an API request, Agent-CoreX hashes the incoming key and checks a Redis cache (5-minute TTL) before querying the database. Invalid keys are negatively cached for 60 seconds to prevent brute-force scanning.

Using your key

Pass your key in the Authorization header of every request:

bash

curl "https://api.agent-corex.com/retrieve_tools?query=read+files&top_k=5" \
  -H "Authorization: Bearer acx_your_key_here"

Or set it as an environment variable (recommended for production):

bash

# .env or shell
AGENT_COREX_API_KEY=acx_your_key_here

The backend accepts both raw API keys (acx_...) and Supabase session JWTs (eyJ...) in the same header. When using the dashboard playground, the session JWT is used automatically.

Revoking a key

To revoke a key, go to Dashboard → API Keys and click Revoke next to the key you want to disable. The key's is_active flag is immediately set to false. The Redis auth cache invalidates within 5 minutes, after which all requests with that key return 401 Unauthorized.

Troubleshooting

I lost my key before copying it.

Create a new key. The lost key must be revoked if it was exposed. There is no way to retrieve the original key — only its prefix is visible in the dashboard.

My key returns 401 Unauthorized.

Check that the key hasn't been revoked (it will show as inactive in the keys list). Also verify you're passing it as a Bearer token, not a query parameter.

The key works in the playground but not in my code.

The playground uses your Supabase session JWT automatically. Make sure your code uses the acx_... key in the Authorization header, not your login credentials.