Creating an App Client
This guide walks Organisation Administrators through creating an App Client — the credentials your systems use to authenticate with the Pearsana API.
Prerequisites
- You must be an Organisation Administrator in Pearsana.
- Your organisation must have API access enabled.
Steps
1. Open the Developer area
Sign in to Pearsana and navigate to your organisation. Select the Developer tab from the organisation menu.
2. Go to App Clients
In the Developer area, select the App Clients tab. You will see a table of any existing App Clients showing their name, Client ID, scopes, and status.
3. Create a new App Client
Click the Create button to open the creation dialog.
Fill in the following fields:
| Field | Required | Description |
|---|---|---|
| Name | Yes | A descriptive name for this client (max 128 characters). Choose something that identifies the system or integration it powers, e.g. "Slate Integration" or "SIS Sync". |
| Description | No | An optional note about what this client is used for. |
| Scopes | Yes | Select at least one scope. These control what the client is allowed to do. See Available Scopes below. |
4. Save your credentials
After you click Create, a dialog displays your new credentials:
- Client ID — a unique identifier for this App Client.
- Client Secret — the secret key used to authenticate.
Save your Client Secret now
The Client Secret is shown only once. Copy it immediately and store it securely (e.g. in a secrets manager or password vault). If you lose it, you will need to delete this App Client and create a new one.
Use the copy buttons next to each value to copy them to your clipboard. You can toggle the Client Secret visibility using the show/hide button.
5. Use your credentials
Use the Client ID and Client Secret to request an access token via OAuth 2.0 Client Credentials. The token is then passed in the Authorization header of every API request.
Available Scopes
Select only the scopes your integration needs. Each scope grants access to a specific set of API operations.
| Scope | Description |
|---|---|
partners.users:write | Create users |
partners.users:read | Read user information |
partners.invitations:write | Create invitations |
partners.invitations:read | Read invitation status |
partners.documents:write | Submit documents |
partners.documents:read | Read document information |
partners.externalRefs:write | Create external references |
partners.externalRefs:read | Look up users by external reference |
partners.verifications:write | Create verifications (required for document verification intents other than store_only) |
Principle of least privilege
Only grant the scopes your integration actually uses. For example, an integration that only submits documents needs partners.documents:write and partners.externalRefs:read — it does not need user or invitation scopes.
Managing App Clients
From the App Clients table you can:
- View the Client ID and assigned scopes for any existing client.
- Delete a client that is no longer needed. This immediately revokes all tokens issued to that client.
Next Steps
- Authentication — learn how to exchange your credentials for an access token.
- API Overview — explore the available endpoints.