Skip to main content
The PERSCOM API uses scopes to control what actions an API key can perform. Scopes let you grant the minimum permissions necessary for each integration.

​
How Scopes Work

Each API key has a set of assigned scopes that determine which endpoints and operations it can access. When you make a request, the API checks whether your key has the required scope for that endpoint. If the key lacks the required scope, the API returns a 403 Forbidden response.

​
Scope Format

Scopes follow the format action:resource:
  • action — The operation type: view, create, update, or delete
  • resource — The resource being accessed, such as user, rank, or assignmentrecord
For example:
  • view:user — Read user data
  • create:rank — Create new ranks
  • update:assignmentrecord — Modify assignment records
  • delete:award — Remove awards

​
Configuring Scopes

When creating an API key, you can either grant all scopes or select specific ones:
  1. Navigate to Integrations > API Keys.
  2. Select New API key.
  3. Choose one of the following:
    • All scopes — Grants full access to all resources and operations
    • Specific scopes — Select only the scopes your integration needs
Important: Follow the principle of least privilege. Only grant the scopes your integration actually requires.

​
Available Scopes

ScopeDescription
view:userView user profiles
create:userCreate new users
update:userUpdate user information
delete:userDelete users

​
Authorization Errors

If your API key lacks the required scope, the API returns a 403 Forbidden response: 
{
  "error": {
    "message": "The API key provided does not have the correct permissions and/or scopes to perform the requested action.",
    "type": "HttpException",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "trace_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}
To resolve this error:
  1. Check which scope the endpoint requires (refer to the endpoint documentation)
  2. Navigate to Integrations > API Keys
  3. Create a new API key with the required scope, or use a key that already has it
Note: You cannot modify scopes on an existing API key. Create a new key with the correct scopes instead.

​
Best Practices

  • Use specific scopes — Avoid granting all scopes unless necessary
  • Create separate keys — Use different API keys for different integrations
  • Review regularly — Audit your API keys and revoke unused ones
  • Document your keys — Use descriptive names to track what each key is used for