> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wearepion.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorisation
To access profile information, you need an access token. Access tokens are bound to a user, and the user first needs to authorise your app. We use the OAuth 2 protocol to manage that authorisation between you, the user and us.
OAuth 2 provides several "grant types" for different use cases. We currently support the "Authorization Code" grant type, intended for apps running on a web server.
If you are not configuring an OAuth 2 library or client, **skip to the next section** to implement the authorisation step manually.
## **Configuring an auth client or library**
Auth libraries and clients that support the OAuth 2 flow can be configured to manage this authorisation for you. Here, you'll find some notes on how to configure your preferred tooling to work with our authorisation service.
### **Table of common options**
These may not exactly match your preferred tooling but they're listed as a guide to help you get set up.
| **Grant type** | Authorisation code. |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorisation URL** | `https://www.studentbeans.com/sso/[consumer supergroup]` - you can see which values you can use for consumer supergroup in the API Reference. |
| **Access Token URL** | `https://accounts.studentbeans.com/oauth/token` |
| **Refresh Token URL** | `https://accounts.studentbeans.com/oauth/token` |
| **Auth scheme** | `Authorization` request header with `Bearer` prefix (recommended), request body or request URL. |
| **Client ID** | The client ID you were given when you registered with us. |
| **Client secret** | The client secret you were given when you registered with us. |
| **Callback URL (or Redirect URI)** | Two names for the same thing. This must be a redirect URI that you have registered with us. |
| **Scope(s)** | Not used. |
| **State** | Not used. |
### **Country**
In addition to the above, you must ensure that your tooling is configured to include the `country` parameter in the authorisation URL. This should be set to `uk` if your client country is the UK, and an ISO 3166 two-letter country code otherwise.
Example:
```
country=uk
```
### **Tracking in the Redirect URI**
You can include additional query parameters on your redirect URI, which may be useful for passing information or tracking users on their round-trip to our authorisation service. These redirect URIs are identical to us:
```
https://example.com/oauth/callback
https://example.com/oauth/callback?campaign=XYZ
https://example.com/oauth/callback?utm_source=xyz&utm_medium=social&utm_campaign=abc&utm_term=search+for+your+website
```
And will all work, as long as you have registered the part before the `?` with us. When we redirect users back to your app, we will include any query parameters that you added.
Please note:
* You must encode the entire redirect URI as a URI component
* You cannot use a parameter called `code` because it will be overwritten with the authorisation grant code.
### **Support**
We are not able to offer technical support for any OAuth 2 client or library and the above is just a guide - it may not exactly match what your preferred tooling offers.
If you need to customise the flow beyond what your tooling supports, **head to the next section** to find out how to implement the authorisation step manually.
## **Manual authorisation flow**
### **Log a user in**
Create a "Log In" link, sending the user to:
```
https://www.studentbeans.com/sso/[consumer supergroup]?response_type=code&client_id=[...]&redirect_uri=[...]&country=[...]
```
Note the domain: `www.studentbeans.com`. These parameters are all required. Descriptions of query parameters and the possible values for the consumer supergroup can be found in [the API reference](/documentation/verify-your-customers/student-beans-sso/reference-and-troubleshooting).
#### **When the user authorises your app**
When your user has successfully logged in, verified (if necessary) and authorised your app, they will be redirected in their browser to your redirect URI, with the `code` query parameter containing an authorisation grant code.
```
https://[redirect URI]?code=[auth code]
```
This authorisation grant code (auth code) is used in conjunction with your client ID and secret to obtain an access token, and cannot be used by itself to access our API. It is valid for two hours.
If you include any additional query parameters in the `redirect_uri` in your login link, they will be added to this URI. If you include one called `code`, it will be overwritten.
### **Get an access token**
Once you have the authorisation grant code, you can make an HTTP POST request to our API to exchange it for an API access token. This access token is what gives you access to the user's verification information.
#### **Request**
```
POST https://accounts.studentbeans.com/oauth/token?grant_type=authorization_code&code=[...]&redirect_uri=[...]&client_id=[...]&client_secret=[...]
```
Note the domain: `accounts.studentbeans.com`. These parameters are all required. Descriptions can be found in [the API reference](/documentation/verify-your-customers/student-beans-sso/reference-and-troubleshooting).
Because we require your client secret here, this request **must** be made from your server, not from client-side JavaScript or a mobile app.
#### **Response**
```
{
"access_token": "[...]",
"token_type": "Bearer",
"expires_in": 2419199,
"refresh_token": "[...]",
"created_at": "[a unix timestamp]"
}
```
```
{
"error": "unsupported_grant_type",
"error_description": "The authorization grant type is not supported by the authorization server."
}
```
Now that you have an access token, you can head to the next step and access your user's verification information. Each access token is scoped to an individual user, so you need to repeat this for each user you want to verify.