Skip to main content
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.

​
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.
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.
1

Go to Admin > Security > Organization API keys

Open the organization API keys page in Plerion.
2

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.
3

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

​
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.
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.