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 Identity Scopes 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 }'

Last updated on

Was this page helpful?