> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caylex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Authentication

> How you and your tools access the Caylex platform: through the Caylex Platform UI with SSO, or programmatically with a platform access token.

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](/auth/server-authentication) for that.

You can access the platform two ways: interactively through the Caylex Platform UI, or programmatically through the REST API.

## Platform UI access (SSO)

Caylex uses SSO for platform access. When you sign up or log in to the Caylex Platform UI, 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 Caylex Platform UI. 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](/integration/connecting)).

### Create a platform access token

<Steps>
  <Step title="Open the Administration page">
    In the [Caylex Platform UI](https://app.caylex.ai), go to the **Administration** page.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

### 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:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.caylex.ai/api/v1/projects \
      -H "Authorization: Bearer $CAYLEX_PLATFORM_TOKEN"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    BASE_URL = "https://api.caylex.ai/api/v1"
    TOKEN = os.environ["CAYLEX_PLATFORM_TOKEN"]

    response = requests.get(
        f"{BASE_URL}/projects",
        headers={"Authorization": f"Bearer {TOKEN}"},
    )
    response.raise_for_status()
    for project in response.json():
        print(project["name"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const BASE_URL = "https://api.caylex.ai/api/v1";
    const TOKEN = process.env.CAYLEX_PLATFORM_TOKEN;

    async function main() {
      const response = await fetch(`${BASE_URL}/projects`, {
        headers: { Authorization: `Bearer ${TOKEN}` },
      });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      const projects = await response.json();
      projects.forEach((p) => console.log(p.name));
    }

    main();
    ```
  </Tab>
</Tabs>

### What you can manage

A platform access token works across the workspace management endpoints. Some of the most common:

| Area                     | Example endpoints                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| **Projects**             | `GET /projects`, `POST /projects`, `PATCH /projects/{project_id}`                                       |
| **Skills**               | `GET /projects/by-name/{project_name}/skills` and the [skill sync](/cookbooks/sync-skills) endpoints    |
| **Usage & billing**      | `GET /usage/summary`, `GET /usage/timeseries`, `GET /usage/credits`                                     |
| **Analytics**            | `GET /analytics/queries-processed`, `GET /analytics/top-tools`                                          |
| **Tool security**        | `GET /projects/{project_id}/tool-security/findings`, `GET /projects/{project_id}/tool-security/summary` |
| **Navigators & servers** | `GET /navigators`, `GET /navigator-instances`, `GET /server-instances`                                  |
| **Widget tokens**        | `POST /widget/mint-token` (see [Agent Widget](/widget/overview))                                        |

<Tip>
  For the full REST API reference (every endpoint with its parameters, request bodies, and response schemas), see the [Caylex REST API documentation](https://developers.caylex.ai/). The machine-readable OpenAPI spec is also available at [`https://api.caylex.ai/api/v1/docs/openapi.yaml`](https://api.caylex.ai/api/v1/docs/openapi.yaml).
</Tip>

### Worked examples

For complete, copy-pasteable workflows built on the Platform API — syncing skills from CI, provisioning a project per customer, and replicating tool permissions across projects — see the [Cookbooks](/cookbooks/overview).

### 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

<CardGroup cols={2}>
  <Card title="Cookbooks" icon="utensils" href="/cookbooks/overview">
    End-to-end recipes for automating common workflows with the Platform API.
  </Card>

  <Card title="REST API Reference" icon="book" href="https://developers.caylex.ai/">
    Browse the full REST API: every endpoint, parameter, and response schema.
  </Card>

  <Card title="Server Authentication" icon="lock" href="/auth/server-authentication">
    See how your end users authenticate with external MCP servers.
  </Card>

  <Card title="Agent Widget" icon="window-maximize" href="/widget/overview">
    Mint widget session tokens with your platform access token to embed a chat agent.
  </Card>

  <Card title="Connecting your agent" icon="plug" href="/integration/connecting">
    Connect an agent to the MCP runtime with a Navigator API key.
  </Card>
</CardGroup>