> ## 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. # Reference and Troubleshooting To register for client access to our single sign-on service, contact your account manager or [visit our website](https://www.wearepion.com/). ## **Authorisation URL** This is where you'll send your users to begin the authorisation process. This is not an API endpoint. ``` https://www.studentbeans.com/sso/key-worker?response_type=code&client_id=cbc97dea-7cba-47dd-b90c-b09684c8f569&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth%2Fcallback%3Freturn_to%3D%2Fpages%2Fstudent-discount&country=uk ``` The URL is made up of several parts. The path tells us which consumer group you want to verify, and the query parameters identify you to us, so we know where to send users back to at the end. It is always in this form: ``` https://www.studentbeans.com/sso/[consumer supergroup]?response_type=code&client_id=[...]&redirect_uri=[...]&country=[...] ``` For detail on which values you can use for "consumer supergroup" in the path, **see the section below on Consumer Supergroups**. ### **Query parameters** | **Parameter** | **Explanation** | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `response_type` | Always the string `code`. This is part of the OAuth 2 specification and `code` is currently the only value we support. | | `client_id` | The client ID we gave you when you registered. **Do not** include your secret in this link, as it will be exposed to the public. | | `redirect_uri` | This is a link to your app or service, where users will be sent when they successfully log in and authorise your app. It must be registered with us. Ensure that this is encoded as a URI component, to avoid any issues with special characters. | | `country` | `uk` for the United Kingdom and an ISO 3166 two-letter country code otherwise. The countries available to you depend on your plan with us. | ### **Success** Successfully authenticated and verified users who authorise your application will be redirected to your app in their browser, at the redirect URI you provide to us. If you have registered more than one redirect URI, we will use the one you included in the URL above. When a user has authorised your app, we will give you an authorisation grant code in the `code` query parameter on the redirect URI. A user who chooses not to authorise your app by clicking "Cancel" will be sent back to the redirect URI you provided *without the authorisation grant code*. This is not an error, and doesn't have any relation to their verification status. Below are some examples of redirect URIs you might send to us, and where we will send the user as a result. ``` https://www.example.com/oauth/callback ``` ``` https://www.example.com/oauth/callback?code=AUTH_GRANT_CODE ``` ``` nativeapp://example.com/oauth/callback ``` ``` nativeapp://example.com/oauth/callback?code=AUTH_GRANT_CODE ``` ``` https://www.example.com/oauth/callback?return_to%2Fanother%2Fpath ``` ``` https://www.example.com/oauth/callback?code=AUTH_GRANT_CODE&return_to=%2Fanother%2Fpath ``` You may need to double-encode custom query parameters in your redirect URI (i.e. encode the query parameter and then encode the entire URI) to prevent issues with special characters in the user's browser. ### **Errors** These are shown on our service but it may be helpful to know their causes in case users report them to you. They are typically caused by an issue with your implementation, but contact your account manager or [support](mailto:support@wearepion.com) if you continue to have issues. #### **The redirect uri included is not valid** Redirect URIs must be registered with us and are matched strictly on scheme, authority and path. Check that the `redirect_uri` parameter you are including is correct. #### **Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method** Ensure that the `client_id` parameter you are including is correct. #### **The authorization server does not support this response type** The `response_type` parameter *must* be `code`. ## **API Endpoints** These endpoints are accessed at `https://accounts.studentbeans.com` - note the subdomain, which is different from the authorisation URL above. ### `POST /oauth/token` Exchange an authorisation grant code for an API access token. ``` POST https://accounts.studentbeans.com/oauth/token?grant_type=authorization_code&code=06dacff6c24747878f459c752b7c5470a219280f51955dba3ac5&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth%2Fcallback%3Freturn_to%3D%2Fpages%2Fstudent-discount&client_id=cbc97dea-7cba-47dd-b90c-b09684c8f569&client_secret=NzdhMTQwZTctY2IyMC00MjYwLWI1NjUtNDNjNWMxOTdmYTI2 ``` These parameters are all required. | **Parameter** | **Explanation** | | :-------------- | :--------------------------------------------------------------------------------------------------------------------------- | | `grant_type` | Always the string `authorization_code`. This is part of the OAuth 2 specification, and the only value we support. | | `code` | The authorisation grant code we included in the redirect URI when we sent the user back to you in the previous step. | | `redirect_uri` | This must be the same as the redirect URI you sent in the login link earlier, *including* *any additional query parameters*. | | `client_id` | The client ID we gave you when you registered. | | `client_secret` | The client secret we gave you when you registered. | #### **Success** On success, you will receive a JSON object containing an access token, refresh token and metadata. ``` { "access_token": "ACCESS_TOKEN", "token_type": "Bearer", "expires_in": 2419199, "refresh_token": "REFRESH_TOKEN", "created_at": "UNIX_TIMESTAMP" } ``` #### **Error** In the case of an error, we will return an appropriate HTTP status code and a JSON-formatted body detailing the problem. ##### **400 Bad Request** ###### `invalid_grant` ``` { "error": "invalid_grant", "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." } ``` This occurs when the authorisation grant code (`code`) you've sent us is invalid, has been used already or has expired. If you have different client IDs across several clients, the code may have been generated for a different client ID. Ensure that the redirect URI *exactly matches* the one you included in the `redirect_uri` parameter when you linked the user to `/oauth/authorize`. It must match exactly, including any custom query parameters this time. ###### `invalid_request` ``` { "error": "invalid_request", "error_description": "Missing required parameter: PARAMETER." } ``` This is an OAuth 2 protocol error. Your request did not include the specified query parameter. If you see this error with the `code` parameter, ensure that users who arrive at your redirect URI without the `code` parameter are handled correctly - this can happen when they decline to authorise your app. ###### `unsupported_grant_type` ``` { "error": "unsupported_grant_type", "error_description": "The authorization grant type is not supported by the authorization server." } ``` This is an OAuth 2 protocol error. Ensure that the `grant_type` query parameter in your request is present and has the value `authorization_code`. We do not currently support other grant types. ##### **401 Unauthorized** ``` { "error": "invalid_client", "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method." } ``` Your client ID or secret is invalid. Check that the request is formatted correctly, and that the client ID and secret exactly match the ones given to you when you registered. ### `GET /api/v3/me.json` Get an authorised user's verification information. ``` GET https://accounts.studentbeans.com/api/v3/me.json ``` You must include a valid access token with your request. ``` GET https://accounts.studentbeans.com/api/v3/me.json ``` Including HTTP header: ``` Authorization: Bearer ACCESS_TOKEN ``` ``` GET https://accounts.studentbeans.com/api/v3/me.json?access_token=ACCESS_TOKEN ``` #### **Success** The user has an active verification in one group. ``` { "sbid_number": "ABC45FG", "verifications": [ { "group": "key-worker", "expires_on": "2026-03-18" } ] } ``` The user has active verifications in more than one group. ``` { "sbid_number": "ABC45FG", "verifications": [ { "group": "student", "expires_on": "2026-03-18" }, { "group": "key-worker", "expires_on": "2026-04-28" } ] } ``` The user has no active verifications. ``` { "sbid_number": "ABC45FG", "verifications": [] } ``` ##### **Response field reference** | **Key** | **Possible values** | **Description** | | :-------------- | :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sbid_number` | 7-character alphanumeric string | A unique identifier for a Student Beans or Beans ID user account. Having an SBID number does not mean that a user is verified with any consumer group. | | `verifications` | Array of JSON objects | This will always be an array but may be empty if a user has no active verifications. | | `supergroup` | String representing a supergroup | This will be one of the consumer supergroups we verify. For data protection, we currently don't list the specific closed consumer groups that a user is part of, except for students and graduates. [You can find a list of the supergroups we may return below.](https://developers.wearepion.com/beans-id-verification/student-beans-sso/api-reference#consumer-supergroups-reference) | | `expires_on` | String representing a date | Formatted as a date (`YYYY-MM-DD`), this is the day on which the relevant verification expires - that is, the first day that the verification will *no longer be valid*. | #### **Error** In case of error, our response will include an appropriate HTTP status code. ##### **400 Bad Request** This response has no body. It occurs when your request to us is malformed. Check that your HTTP client is configured correctly and is sending required HTTP request headers, like `Host`. ##### **401 Unauthorized** This response may have a body: ``` { "message": "Unauthorized" } ``` It occurs when the access token you provide is missing, malformed or invalid. Ensure that you are setting either the `Authorization` header or the `access_token` query parameter, and that the access token is one you got from the `/oauth/token` API endpoint above. You cannot use the authorisation grant code for this endpoint. ##### **403 Forbidden** This response has no body. This error may occur if your request has no `User-Agent` header. ##### **404 Not Found** This response may have a body: ``` { "message": "Not Found" } ``` This can happen with access tokens granted in the past, where the user they referred to has since asked us to delete their account. ## **Consumer Supergroups reference** Below is a reference of *consumer supergroups* and the *closed consumer groups* they contain, with the string value that will appear in the `supergroup` key in the API response. | **API value** | **Supergroup** | **CCGs** | **Theme** | | :------------------ | :---------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `student` | Students | Just students | Young adults at a key transitional life stage, forming lifelong brand loyalties. We verify students in post-16 and higher education. | | `graduate` | Graduates | Just graduates | Recently graduated students — up to 5 years after graduation. | | `key-worker` | Key Worker | - Military and veterans - Healthcare workers - First responders - Teachers - Charity workers | Individuals dedicated to community and public welfare; the backbone of the nation's workforce. | | `social-assistance` | Social Assistance | - Low-income - Disabled people - New parents | Individuals and families who qualify for support based on specific life circumstances or needs. |