API Reference & 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

https://www.studentbeans.com/sso/student-graduate?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)

https://www.example.com/oauth/callback

https://www.example.com/oauth/callback?code=AUTH_GRANT_CODE

Alternative scheme

nativeapp://example.com/oauth/callback

nativeapp://example.com/oauth/callback?code=AUTH_GRANT_CODE

Custom query parameters

https://www.example.com/oauth/callback?return_to%2Fanother%2Fpath

https://www.example.com/oauth/callback?code=AUTH_GRANT_CODE&return_to=%2Fanother%2Fpath

info

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.

Authorization header (recommended)

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

Including HTTP header:

Authorization: Bearer ACCESS_TOKEN

Query parameter

GET https://accounts.studentbeans.com/api/v3/me.json?access_token=ACCESS_TOKEN

Success

Verified (one supergroup)

The user has an active verification in one supergroup.

{
  "sbid_number": "ABC45FG",
  "verifications": [
    {
        "supergroup": "student-graduate",
        "expires_on": "2026-03-18"
    }
  ]
}

Verified (several supergroups)

The user has active verifications in more than one supergroup.

{
  "sbid_number": "ABC45FG",
  "verifications": [
    {
        "supergroup": "student-graduate",
        "expires_on": "2026-03-18"
    },
    {
        "supergroup": "key-worker",
        "expires_on": "2026-04-28"
    }
  ]
}

Not verified

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. 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-graduate	Student & Graduate	Students Graduates	Young adults at a key transitional life stage, forming lifelong brand loyalties. We verify students in post-16 and higher education.
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.