Skip to main content
Caylex has two layers of authentication. Platform authentication (covered here) controls how you and your tools access the Caylex platform itself. Server authentication controls how your end users authenticate with external MCP servers; see Server Authentication for that. You can access the platform two ways: interactively through the dashboard, or programmatically through the REST API.

Dashboard access (SSO)

Caylex uses SSO for platform access. When you sign up or log in to the Caylex dashboard, you authenticate through the platform’s identity provider. This gives you access to manage your organization’s projects, servers, navigators, and analytics.

Programmatic access with a platform access token

The Caylex platform exposes a REST API for managing your workspace without clicking through the dashboard. It covers projects, skills, usage, analytics, tool security, and more. Authenticate with a platform access token and call the API from a script, a CI pipeline, or your own backend. This is the control plane for your workspace. It is separate from the runtime connection your agents use to call tools, which uses a Navigator API key instead (see Connecting your agent).

Create a platform access token

1

Open the Administration page

In the Caylex dashboard, go to the Administration page.
2

Create a token

Create a new platform access token and give it a descriptive name (for example, ci-skill-sync). Optionally set an expiry date.
3

Copy the token

Copy the token value and store it in a secret manager or CI secret. The raw token is shown only once. If you lose it, revoke it and create a new one.
A platform access token has admin scope over your entire workspace. Treat it like a password: keep it server-side, never commit it to version control, and never expose it to a browser.

Authenticate

Send the token in the Authorization header as a Bearer token against the https://api.caylex.ai/api/v1 base URL. To verify your token works, list your projects:
curl https://api.caylex.ai/api/v1/projects \
  -H "Authorization: Bearer $CAYLEX_PLATFORM_TOKEN"

What you can manage

A platform access token works across the workspace management endpoints. Some of the most common:
AreaExample endpoints
ProjectsGET /projects, POST /projects, PATCH /projects/{project_id}
SkillsGET /projects/by-name/{project_name}/skills and the skill sync endpoints below
Usage & billingGET /usage/summary, GET /usage/timeseries, GET /usage/credits
AnalyticsGET /analytics/queries-processed, GET /analytics/top-tools
Tool securityGET /projects/{project_id}/tool-security/findings, GET /projects/{project_id}/tool-security/summary
Navigators & serversGET /navigators, GET /navigator-instances, GET /server-instances
Widget tokensPOST /widget/mint-token (see Agent Widget)
For the full REST API reference (every endpoint with its parameters, request bodies, and response schemas), see the Caylex REST API documentation. The machine-readable OpenAPI spec is also available at https://api.caylex.ai/api/v1/docs/openapi.yaml.

Example: sync skills from your repository

A common use case is keeping a local repository of skills in sync with a Caylex project from CI. The skill sync endpoints address your project by name and each skill by its SKILL.md frontmatter name, so your tooling never has to track Caylex UUIDs.
Project names are matched exactly and are case-sensitive. URL-encode names that contain spaces. For example, Production Project becomes Production%20Project.
BASE="https://api.caylex.ai/api/v1"
PROJECT="Production%20Project"
AUTH="Authorization: Bearer $CAYLEX_PLATFORM_TOKEN"

# List every skill in the project
curl "$BASE/projects/by-name/$PROJECT/skills" -H "$AUTH"

# Fetch one skill, including its SKILL.md body
curl "$BASE/projects/by-name/$PROJECT/skills/code-review" -H "$AUTH"

# Add a new skill (409 if it already exists)
curl -X POST "$BASE/projects/by-name/$PROJECT/skills" -H "$AUTH" \
  -F "file=@./skills/code-review/SKILL.md"

# Replace an existing skill (404 if it doesn't exist yet)
curl -X PUT "$BASE/projects/by-name/$PROJECT/skills/code-review" -H "$AUTH" \
  -F "file=@./skills/code-review/SKILL.md"

# Remove a skill
curl -X DELETE "$BASE/projects/by-name/$PROJECT/skills/code-review" -H "$AUTH"
For a skill bundled with extra files (scripts, references), upload a ZIP of the skill directory in place of the SKILL.md. The file part accepts either.
Use POST to add a new skill and PUT to replace one. POST returns 409 if the skill already exists, and PUT returns 404 if it doesn’t, so CI can distinguish a first-time upload from an update instead of silently overwriting.

Security best practices

  • Keep tokens server-side. Call the Platform API from your backend or CI only, never from a browser or mobile client.
  • Use a secret manager. Store tokens in your CI provider’s secrets or a secret manager, not in code or .env files committed to git.
  • Set an expiry. Give tokens an expiry date where possible, and create separate tokens for separate systems so you can revoke one without disrupting others.
  • Rotate and revoke. Rotate tokens periodically, and revoke any token immediately from the Administration page if it may be compromised.

Next steps

REST API Reference

Browse the full REST API: every endpoint, parameter, and response schema.

Server Authentication

See how your end users authenticate with external MCP servers.

Agent Widget

Mint widget session tokens with your platform access token to embed a chat agent.

Connecting your agent

Connect an agent to the MCP runtime with a Navigator API key.