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

# Organization API keys

> Create and manage organization-scoped API keys for the Plerion organization API

With **organization API keys**, you can authenticate to the organization endpoints of the Plerion API. An organization key is scoped to your whole Plerion organization rather than to a single tenant, so it is the credential used by tools that act across the organization, such as an identity provider connected through [SCIM provisioning](/guides/administration/scim/overview).

***

## Organization keys and tenant keys

Plerion has two kinds of API key, and each works on one part of the API.

* **Organization API keys** authenticate requests to `/v1/organization/*`. They resolve the organization from the key itself, so no request names an organization.
* **Tenant API keys** authenticate requests to `/v1/tenant/*`, the findings, assets, and alerts endpoints described in the [API reference](/api-reference/index).

The two are not interchangeable. An organization key sent to a tenant endpoint is rejected, and so is a tenant key sent to an organization endpoint.

***

## Access levels

The access level is chosen when the key is created and cannot be changed afterwards.

* **read.** Read-only. The key can call the organization endpoints that only retrieve data.
* **readWrite.** Read and write. Required by anything that creates or changes data, including SCIM provisioning.

Give a key the lowest access level that does the job. To change the access level of an existing key, create a new key and revoke the old one.

***

## Steps to create an organization API key

Only **Organization Admins** can create organization API keys.

<Steps>
  <Step title="Go to Admin > Security > Organization API keys">
    Open the organization API keys page in Plerion.
  </Step>

  <Step title="Click Create API key">
    Provide the following:

    * **Name**, between 2 and 64 characters. It is fixed once the key is created, so name it after the tool that will use it, for example **Okta SCIM**.
    * **Access level**, either **read** or **readWrite**.
  </Step>

  <Step title="Copy the key">
    Plerion shows the key once and stores only a hash of it. Copy it straight into your secret manager or the tool that needs it. If you lose it, revoke the key and create another.

    <Warning>
      Treat an organization API key like a password. It carries organization-wide access. Do not store it in plain text or commit it to a code repository.
    </Warning>
  </Step>
</Steps>

An organization can hold up to five keys at a time. Revoking a key frees its slot.

***

## Using an organization API key

Send the key as a bearer token in the `Authorization` header, over HTTPS. Requests over plain HTTP, and requests without a key, fail.

```
export PLERION_API_URL={region}.api.plerion.com
export PLERION_ORG_API_KEY=your-organization-api-key

curl --request GET \
  --url "https://$PLERION_API_URL/v1/organization/scim/v2/Users" \
  --header "Authorization: Bearer $PLERION_ORG_API_KEY"
```

***

## Revoking a key

Revoke a key from `Admin` > `Security` > `Organization API keys`. Revocation takes effect immediately, and any tool still presenting the key starts receiving unauthorized responses.

Plerion also revokes keys automatically. When a user is deprovisioned, whether by an administrator or by your identity provider, every API key that user created is revoked along with their access.

<Info>
  This is why a key used for SCIM provisioning should be created by a break-glass admin. A break-glass admin cannot be deprovisioned by an identity provider, so the credential your identity provider depends on cannot be revoked by the identity provider's own sync. See [Break-glass admins](/guides/administration/scim/overview#break-glass-admins).
</Info>