Reference and Troubleshooting

To register for client access to our single sign-on service, contact your account manager or visit our website.

Authorisation URL

This is where you’ll send your users to begin the authorisation process. This is not an API endpoint.

Example

A detailed view of the auth url

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.

Default (HTTPS)
Alternative Scheme
Custom Query Parameters

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 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.

Example

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.

Example

GET https://accounts.studentbeans.com/api/v3/me.json

You must include a valid access token with your request.

Authorisation Header (recommended)
Query Parameter

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

Verified (one supergroup)
Verified (several supergroups)
Not Verified

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.
`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.

Get Started

Verify your Customers

Track every Transaction

Check iD Status

Connect with your Customers

Language & Territories

Reference and Troubleshooting

Authorisation URL

Query parameters

Success

Errors

The redirect uri included is not valid

Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method

The authorization server does not support this response type

API Endpoints

`POST /oauth/token`

Success

Error

400 Bad Request

`invalid_grant`

`invalid_request`

`unsupported_grant_type`

401 Unauthorized

`GET /api/v3/me.json`

Success

Response field reference

Error

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Consumer Supergroups reference

​Authorisation URL

​Query parameters

​Success

​Errors

​The redirect uri included is not valid

​Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method

​The authorization server does not support this response type

​API Endpoints

​POST /oauth/token

​Success

​Error

400 Bad Request

invalid_grant

invalid_request

unsupported_grant_type

401 Unauthorized

​GET /api/v3/me.json

​Success

Response field reference

​Error

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

​Consumer Supergroups reference

Authorisation URL

Query parameters

Success

Errors

The redirect uri included is not valid

Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method

The authorization server does not support this response type

API Endpoints

`POST /oauth/token`

Success

Error

`invalid_grant`

`invalid_request`

`unsupported_grant_type`

`GET /api/v3/me.json`

Success

Error

Consumer Supergroups reference