Personal Access Tokens
A Personal Access Token (PAT) is a sequence of characters that can be used to authenticate a user instead of a password. PATs don’t support role-based access control, meaning they can only be assigned permissions and tenants, not roles.
Users can create their own PATs, but can only assign permissions that they currently possess to a PAT. Similarly, users can only assign tenants to a PAT if the tenants are currently assigned to the user’s tenant scope.
If a user loses permissions or tenant assignments, and those permissions and tenants were previously assigned to a PAT, the PAT will also lose those permissions and tenant assignments, even if they’re still present in the PAT.
Users can authenticate API requests using a PAT instead of login credentials. PATs function similarly to JWTs, which are created when users authenticate through native login or SSO login, but users can configure PAT details, including permissions, tenants, and token expiration date.
Note
PATs can be configured to never expire, but we strongly recommend specifying an expiration date for PATs in production environments.
Managing Personal Access Tokens
Users can create PATs through the UI by navigating to User Settings > Personal Access Tokens > Create Token.
PATs cannot be modified once created. Users can only replace a PAT by first deleting it, then creating a new PAT.
Each user can have up to 3 PATs at a time. Users can submit a request to their Socotra representative to increase this limit to 10.
Users can view PAT details through the UI by navigating to User Settings > Personal Access Tokens, then selecting a PAT.
Note
Token values can only be viewed immediately after creating a PAT, so make sure to save your token value in a secure password manager.
Refer to the Authentication API documentation for more details on managing PATs.
Using Personal Access Tokens in Postman
PATs can be used to authenticate requests in Postman by selecting a sample request from our Postman sample collection, such as the Describe Current User request located in Socotra Sample Collection > Auth > Users.
Navigate to the Authorization tab, select Bearer Token from the Auth Type drop-down list, and then paste your token value in the Token field.
Next, select Socotra Sample Environment from the environment drop-down list in the upper right corner of the request window.
Finally, click the Send button.
As long as your PAT has the necessary permissions and tenant assignments to access the API endpoint used in the sample request, you should be able to successfully submit the request and receive a 200 OK response.
Best Practices
Software integrations, scripts, and AI agents should only use PATs for authentication. Native login and SSO should only be used by humans logging in through the Socotra Insurance Suite UI or authenticating API requests through Postman.
Permissions should be assigned based on the principle of least privilege. This means that PATs should only be assigned permissions that are strictly necessary for the user to complete their work.