Skip to main content

Managing API Keys

Every request to the Revelry Ai API is authenticated with an API key sent in the Authorization header:

Authorization: Bearer YOUR_API_KEY

There are two kinds of key. Both use the same header and the same endpoints; they differ in who they act as.

Organization API KeyPersonal API Key
Acts asThe organizationYou, within one organization
PermissionsA fixed set of API permissions for the organizationYour own permissions in that organization
Created fromOrganization Settings, Developer tabMy Account, Personal API Keys
Who can createOrganization adminsAny active member
Who can revokeOrganization adminsYou, or an organization admin
Chats it createsOwned by the organizationOwned by you
AttributionRecorded as the key's nameRecorded as the key's name, tied to your account

Use an Organization API key for shared integrations and back-end services that act on behalf of the whole organization. Use a Personal API key to connect MCP clients, scripts, or integrations that should act as you and be limited to what you can already do in the app.

Organization API Keys​

Creating an Organization API Key​

  1. Navigate to Settings > Organization > Developer.
  2. Under API Keys, click Create API Key.
  3. Give the key a descriptive name and click Save.
  4. Copy the key and store it somewhere safe.

Important: The key is shown only once. If it is lost, revoke it and create a new one.

Create a separate named key for each application or integration rather than sharing one key. If a key is compromised, you can revoke it without breaking your other integrations.

Revoking an Organization API Key​

  1. Navigate to Settings > Organization > Developer.
  2. Find the key under API Keys and click Revoke.

Revoked keys stop working immediately and cannot be reactivated. They stay in the list for audit purposes, and you can create a new key with the same name.

Personal API Keys​

A Personal API key is scoped to you within a single organization. If you belong to several organizations, create a key in each one you need to reach; one key never spans organizations.

Requests made with a Personal API key carry exactly your permissions in that organization. If you cannot do something in the app, you cannot do it with your key. Platform-level administration is never available through a Personal API key, even for super admins.

Personal API keys are enabled per organization. If you don't see the Personal API Keys section in My Account, ask your organization admin to enable it.

Creating a Personal API Key​

  1. Open My Account from the account menu at the bottom of the left navigation.
  2. Under Personal API Keys for the organization you want, click Create Personal API Key.
  3. Give the key a name and click Save.
  4. Copy the key. Like Organization keys, it is shown only once.

Revoking a Personal API Key​

You can revoke your own keys from My Account > Personal API Keys.

Organization admins can see and revoke every member's Personal API keys from Settings > Organization > Developer, under the Personal API Keys panel. The table shows each key's owner, creation date, and last use.

A Personal API key also stops working automatically when:

  • Your membership in the organization is removed or deactivated.
  • Your account is deactivated.
  • The organization disables Personal API keys.

Attribution​

Anything created through the API records which key created it. This applies to artifacts and their versions, Skills and their versions, collections, uploaded chat files, and workflow runs.

In the app, this shows up wherever a creator or author is displayed. An artifact's Version History lists an API-created version as API key: <name>, and a Skill's details page shows the key's name as its creator. If the key has since been deleted, the entry reads Deleted API key.

Best Practices​

  • Never expose API keys in client-side code or commit them to source control.
  • Store keys in environment variables or a secrets manager.
  • Use one key per integration so a compromised key can be revoked on its own.
  • Prefer Personal API keys for anything that acts as an individual, so permissions and attribution follow the person.
  • Rotate keys periodically by creating a new key, switching your integration over, then revoking the old one.

Next Steps​