Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.perscom.io/llms.txt

Use this file to discover all available pages before exploring further.

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