Partner API
This guide is designed to help our partners integrate seamlessly with our platform, allowing them to create and manage Organisations and Clients under their accounts. Each Organisation can be uniquely customised with different logos, names, available products, scopes, and URLs. Additionally, Organisations can have multiple clients, each associated with a single product.
The Partner API offers robust endpoints to facilitate these operations, including token generation, Organisation management, and Client management. This documentation provides detailed information on how to authenticate, create, and manage organisations and clients.
Billing
Billing is done at the account level, with a detailed usage breakdown provided for each organization and client. This allows for transparent tracking of resource utilization and costs, making it easier to manage and allocate expenses accurately.
Authentication
To interact with the Partner API, you will first need to obtain a token by exchanging your partner client ID and secret. This token will be used to authenticate subsequent requests. In order to receive your partner credentials, please reach out to our sales team.
POST /token
- Used to exchange the client_id and client_secret
- The returned token is a JWT with a 24h expiry
Example Request
curl -X POST https://api.oneid.uk/v1/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret"Example Response
HTTP/1.1 200 OK{ "access_token":"eyJz93a...k4laUWw", "token_type":"Bearer", "expires_in":86400}Organisation Management
The Organisation Management API provides endpoints for creating and updating Organisations. Each request to these endpoints must include a valid JWT token in the Authorization header Authorization: Bearer {token} . This token can be acquired from the /token endpoint.
Data structure
Attributes
All fields are optional except those marked required.
Example:
{ "id":"string", // generated, not part of the request "parent_id": "string" // the UUID of the parent organisation "name": "string", // required "enable_custom_logo": "bool", "allowed_scopes": ["string"], "allowed_products":["string"], "allowed_provider_groups": ["string"], "has_production_access": "bool"}Endpoints
GET /organisations
curl -X GET https://api.oneid.uk/v1/organisations \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json"POST /organisations
If no allowed products are supplied then the value will be defaulted to the products attached to the Client's Organisation. When allowed products are supplied then the value can be a subset of the products attached to the Organisation.
Has Production access can only be set to true if the attached Organisation is a production Organisation.
curl -X POST https://api.oneid.uk/v1/organisations \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json" \-d '{ "name": "test org", "allowed_scopes": ["accounts", "address", "date_of_birth"], "allowed_products": ["sign_up_plus"], "allowed_provider_groups": ["sandbox-participating", "idscan"], "has_production_access": true}'GET /organisations/:id
curl -X GET https://api.oneid.uk/v1/organisations/{organisation_id} \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json"PUT /organisations/:id
curl -X PUT https://api.oneid.uk/v1/organisations/{organisation_id} \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json" \-d '{ "name": "test org", "allowed_scopes": ["accounts", "address", "date_of_birth"], "allowed_products": ["sign_up_plus"], "allowed_provider_groups": ["sandbox-participating", "idscan"], "has_production_access": true, "enabled": true"}'Client Management
The Client Management API deals with OAuth2 clients for each Organisation. OAuth2 Clients represent individual applications. Each Client can be associated with a single product and must be registered with valid redirect URIs.
All endpoints require a valid JWT created by the /oidc/token endpoint.
Data structure
All fields are optional except those marked required.
Values available to the product field can be found in the product id column on the (Link Removed)#here page.
Example:
{ "id": "string", // generated, not part of the request "name":"string", // required "token_signing_algorithm": "", // Enum of the following values PS256, ES384 or ES512 "additional_scopes": ["string"], "required_scopes": ["string"], "return_urls": ["string"], "is_production": "bool", "selected_product": "sign_up", "secret":"string", // generated, not part of the request, "enabled": true}Endpoints
GET /organisations/:id/clients
curl -X GET https://api.oneid.uk/v1/organisations/{organisation_id}/clients \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json"POST /organisations:/id/clients
curl -X POST https://api.oneid.uk/v1/organisations/{organisation_id}/clients \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json" \-d '{ "name": "test-client", "token_signing_algorithm": "PS256", "additional_scopes": ["accounts", "address"], "required_scopes": ["openid", "profile"], "return_urls": ["https://example.com"], "selected_product": "sign_up", "allowed_provider_groups": ["sandbox-participating"], "is_production": false, "enabled": true}'GET /clients/:id
curl -X GET https://api.oneid.uk/v1/clients/{client_id} \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json"PUT /clients/:id
curl -X PUT https://api.oneid.uk/v1/clients/{client_id} \-H "Authorization: bearer <token_from_above>" \-H "Content-Type: application/json" \-d '{ "name": "test-client", "token_signing_algorithm": "PS256", "additional_scopes": ["accounts", "address"], "required_scopes": ["openid", "profile"], "return_urls": ["https://example.com"], "selected_product": "sign_up", "allowed_provider_groups": ["sandbox-participating"], "is_production": false, "enabled": true}'