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

# Authentication

> Create an API key and obtain access tokens for the Cyrisma New Partner API

The New Partner API authenticates with an **API key**: a client ID and client secret pair. You
exchange the pair for a short-lived bearer token, and send that token on every request.

## Create an API key

API keys are created and managed in the Cyrisma web platform. Sign in, then go to
**Settings → API Keys**.

API keys are available at both the organization and the instance level. A key belongs to the
organization or instance it is created under.

<Steps>
  <Step title="Open Settings → API Keys">
    The screen lists existing keys with their access level, status, creation date, and last use.
  </Step>

  <Step title="Create a key">
    Supply a name, choose an access level, and choose whether the key applies to sub-organizations.
  </Step>

  <Step title="Store the client secret">
    The client ID and client secret are displayed once, when the key is created.
  </Step>
</Steps>

| Field                        | Description                                                                                                                                               |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                         | A label to identify the key in the list.                                                                                                                  |
| Access level                 | **Read** for reporting only. **Read and write** to also provision tenants and manage users.                                                               |
| Applies to sub-organizations | Whether the key also covers organizations and instances beneath the one it is created under. Leave this off to restrict the key to a single organization. |

<Warning>
  The client secret is displayed once, at the moment the key is created. It cannot be retrieved
  afterwards. Store it before leaving the page. If a secret is lost, revoke the key on the same
  screen and create a new one; the replacement has a new client ID.
</Warning>

Revoking a key takes effect immediately.

## Request an access token

<Info>
  The values shown throughout this documentation are examples only.
</Info>

```bash theme={null}
curl -fsS -X POST "https://ccnnnnnn.cyrisma.com/ta/v1/auth/client-token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "pc_9f2c41d8a7b34e10",
    "client_secret": "pcs_1a2b3c4d5e6f7g8h9i0j",
    "requested_scopes": ["pulse.read"]
  }'
```

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-08-30T10:14:22Z",
  "subject_type": "machine_client"
}
```

Tokens are valid for 60 minutes. Request a new token when the current one expires; there is no
refresh token. Invalid or revoked credentials return `401`.

## Send the token

```bash theme={null}
curl -fsS \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://ccnnnnnn.cyrisma.com/app/pulse/v1/partner/vulnerabilities/cves?page_size=100"
```

## Scopes

| Scope         | Access level   | Grants                                                                    |
| ------------- | -------------- | ------------------------------------------------------------------------- |
| `pulse.read`  | Read           | Reading reporting data, tenants, and usage.                               |
| `pulse.write` | Read and write | Provisioning tenants, managing users, and changing authentication policy. |

Request only the scopes an integration needs. Requesting a scope the key does not hold is rejected.

## Tenant scope

Every request is restricted to the organizations and instances the key is authorized for: the one it
was created under, plus everything beneath it when the key applies to sub-organizations.

Narrow a request with `tenant_ids`, a comma-separated list of tenant identifiers. Add
`include_descendants=true` to widen each identifier to that tenant and everything beneath it.

```bash theme={null}
curl -fsS \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://ccnnnnnn.cyrisma.com/app/pulse/v1/partner/vulnerabilities/cves?tenant_ids=$TENANT_ID&include_descendants=true"
```

Requesting a tenant outside the authorized set returns `403`, whether or not that tenant exists.

Use `GET /app/pulse/v1/partner/tenants` to list the tenants a key can reach.