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 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.
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
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
}
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.
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"
}
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"
}'
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.
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
}
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
}'
