Scopes API
The scopes API allows the creation of new scopes via a REST API. It can be used in scripts to add many scopes at the same time, or to edit or delete scopes.
All endpoints are protected with API client credentials (either client secret basic or private key JWT, depending on the
client authentication method). It requires an API client with the
onegini_api_config (Config API) scope.
Authentication
All endpoints in the Config API are secured by API client credentials.
It requires an API client with the onegini_api_config (Config API) scope.
Scope API endpoints
Read scope
This returns the configuration of a specific scope.
- Endpoint:
/api/v1/configuration/scopes/{scope} - Method: GET
Path parameters:
| Param | Required | Description |
|---|---|---|
| scope | yes | Unique identifier of the scope |
Example request:
GET /api/v1/configuration/scopes/openid HTTP/1.1
Host: onewelcome.example.com
Example success response:
HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"scope_id": "openid",
"authentication_level": 0,
"usage_limit": 0,
"service_endpoint": "",
"persistent_consent": true,
"descriptions": {
"de": "openid",
"en": "openid",
"fr": "openid",
"nl": "openid"
}
}
In the event of an error, one of the generic error codes is returned.
Create scope
This creates a new scope from scratch
- Endpoint:
/api/v1/configuration/scopes - Method: POST
JSON body parameters:
| Param | Required | Example | Description |
|---|---|---|---|
| scope_id | yes | "openid" | Scope identifier. At most 20 characters: letters (a-z, A-Z), digits (0-9), underscores (_) and hyphens (-) are permitted. |
| authentication_level | no | 0 | Authentication level. If not provided, it defaults to 0. The required authentication level of the user. If the authentication level doesn't match, the user is redirected to the configured authentication server. |
| usage_limit | no | 0 | [DEPRECATED] Usage limit. Since being deprecated, its value can only be 0. |
| service_endpoint | no | "https://onegini.example.com" | Service endpoint. If not provided, it defaults to null. |
| verification_failed_endpoint | no | "https://onegini.example.com" | Verification failed endpoint. If not provided, it defaults to null. |
| persistent_consent | no | true | Persistent consent. If not provided, it defaults to false. When true, the user must give consent for this scope during only the first authorization request. When false, the user must give consent for every authorization request with this scope. |
| descriptions | no | Descriptions. If not provided, no descriptions are stored. |
Example request:
POST /api/v1/configuration/scopes HTTP/1.1
Host: onewelcome.example.com
Content-Type: application/json
{
"scope_id": "insurance"
}
Example success response:
HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/configuration/scopes/insurance
The success response body is empty.
In the event of an error, one of the generic error codes is returned.
Update scope
Some fields can be updated after creating a scope.
- Endpoint:
/api/v1/configuration/scopes/{scope} - Method: PATCH
Path parameters:
| Param | Required | Description |
|---|---|---|
| scope | yes | Unique identifier of the scope |
JSON body parameters:
Fields that are sent in the request are changed to the new value. Fields that are not sent are reset to default values.
| Param | Required | Example | Description |
|---|---|---|---|
| scope_id | yes | "openid" | Scope identifier. At most 20 characters: letters (a-z, A-Z), digits (0-9), underscores (_) and hyphens (-) are permitted. |
| authentication_level | no | 0 | Authentication level. If not provided, it defaults to 0. The required authentication level of the user. If the authentication level doesn't match, the user is redirected to the configured authentication server. |
| usage_limit | no | 0 | [DEPRECATED] Usage limit. Since being deprecated, its value can only be 0. |
| service_endpoint | no | "https://onewelcome.example.com" | Service endpoint. If not provided, it defaults to null. |
| verification_failed_endpoint | no | "https://onewelcome.example.com" | Verification failed endpoint. If not provided, it defaults to null. |
| persistent_consent | no | true | Persistent consent. If not provided, it defaults to false. When true, the user must give consent for this scope during only the first authorization request. When false, the user must give consent for every authorization request with this scope. |
| descriptions | no | Descriptions. If not provided, no descriptions are stored. |
Example request:
PATCH /api/v1/configuration/scopes/insurance HTTP/1.1
Host: onewelcome.example.com
Content-Type: application/json
{
"scope_id": "insurance",
"descriptions": {
"nl": "verzekering"
}
}
Example success response:
HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
The success response body is empty.
In the event of an error, one of the generic error codes is returned.
Delete scope
This removes a scope.
- Endpoint:
/api/v1/configuration/scopes/{scope} - Method: DELETE
Path parameters:
| Param | Required | Description |
|---|---|---|
| scope | yes | Unique identifier of the scope |
Example request:
DELETE /api/v1/configuration/scopes/insurance HTTP/1.1
Host: onewelcome.example.com
Example success response:
HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Error codes
One of the following responses is returned, containing a JSON object with an error code, a message, and details about the error.
| HTTP status | Error code | Message |
|---|---|---|
| 400 | invalid_request | One or more parameters is missing or incorrect. The details contain the missing or incorrect parameters. |
| 401 | unauthorized | Provide valid credentials to get access to the API. |
| 403 | forbidden | Operation is not allowed for the current user |
| 404 | not_found | Scope configuration cannot be found |
| 409 | conflict | The Scope already exists |
