Admin APIs
These APIs are to create/read/update/delete specific configuration related to external resources for a given application instance.
DevOps Usage
Note: Instance endpoints require Bearer Authentication. The Configuration endpoints currently support both Bearer and Basic authentication. Basic authentication will be removed in the future. The bearer tokens (JWT access token) are validated using the Token Server keys with the /oauth/v1/keys endpoint. When the validation fails, an error will be returned. Refer to the Token Server configuration for further details.
Console UI usage
Access to the configuration APIs can be granted either by scope (css_configuration) or by policies assigned to the user. The scope is
primarily used when the self styling UI is embedded within the IdP admin or if you want to call the APIs directly. The policies for a given user are fetched
via the user-info endpoint on the access-engine for the Onegini Tenant. An overview of the different policies and how to assign them can be found in the
console-ui.
Refer to the console-ui docs for self-styling for actual usage.
Instance APIs
Check if instance exists
This endpoint checks if particular instance is available in the system
- Endpoint:
/api/v1/instance/{instance_id} - Request method: GET
- Authentication: Bearer
Example request
GET /api/v1/instance/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b HTTP/1.1
Authorization: Bearer eyJraWQiOiJmNDYzYmYyYy04MWE2LTQ5NzktODJhNS1hYTVkMDMyYjZmZTUiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIw...
Content-Type: application/json;charset=UTF-8
Host: external-resources.example.com
{
"instance_id": "a31dbf27-75d5-45c6-9acd-2fb1376d4e3b"
}
Request path parameters:
| Parameter | Description |
|---|---|
instance_id |
The unique identifier for a customer's application instance |
Example response
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
{
"instance_id": "a31dbf27-75d5-45c6-9acd-2fb1376d4e3b"
}
Possible responses:
| Http status code | Response Description |
|---|---|
| 200 | Instance exists |
| 404 | Instance not exists |
Fetch all instances
This endpoint is fetching all available instances in the application
- Endpoint:
/api/v1/instance - Request method: GET
- Authentication: Bearer
Example response
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
{
"instances": [
{
"id": "a31dbf27-75d5-45c6-9acd-2fb1376d4e3b"
},
{
"id": "b42ecg38-86e6-56d7-0bde-3gc2487e5f4c"
}
]
}
Possible responses:
| Http status code | Response Description |
|---|---|
| 200 | Instance list fetched |
Delete instance
This endpoint deletes the instance_id of a customer with associated configuration and all synchronized files in AWS S3
- Endpoint:
/api/v1/instance/{instance_id} - Request method: DELETE
- Authentication: Bearer
Path parameters:
| Param | Required | Description |
|---|---|---|
instance_id |
yes | The unique identifier for a customer's application instance |
Possible responses:
| Http status code | Response description |
|---|---|
| 204 | Instance was deleted |
| 404 | Provided instance does not exists |
Configuration APIs
Create Configuration
This will create a single instance_id's configuration.
- Endpoint:
/api/v1/config/{instance_id} - Request method: POST
- Authentication: Basic Auth or Bearer
Path parameters:
| Param | Required | Description |
|---|---|---|
instance_id |
yes | The unique identifier for a customer's application instance. |
Request headers:
| Header | Required | Description |
|---|---|---|
X-Onegini-Instance |
yes | Must have the same value as the path parameter instance_id. Make sure its value is set by a trusted proxy in front of this application. It has to be a valid UUID. |
JSON body request keys:
| Param | Required | Description |
|---|---|---|
remote_url |
yes | The remote url of the git repo. |
authentication_type |
yes | Enum for the type of authentication used. Valid values: NONE, BASIC. |
username |
depends | The username of the git repo. Required if BASIC authentication_type is selected. |
password |
depends | The password of the git repo or personal token. Required if BASIC authentication_type is selected. |
synchronization_type |
yes | The type of synchronization to be used when retrieving references from the git repository. Possible values are PRODUCTION and DEVELOPMENT. Depending on the option selected, different reference lists will be available when configuring synchronization in the admin panel. These options can also be changed through the admin panel. |
Example request Initial save of configuration
POST /api/v1/config/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-Onegini-Instance: a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
Host: external-resources.example.com
Content-Type: application/json
{
"remote_url": "https://github.com/CustomerABC/application.git",
"authentication_type": "BASIC",
"username": "CustomerABC",
"password": "123456789",
"synchronization_type" : "PRODUCTION"
}
Successful response
HTTP/1.1 201 CREATED
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/config/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
{
"remote_url": "https://github.com/CustomerABC/application.git",
"authentication_type": "BASIC",
"username": "CustomerABC",
"selected_reference": "null"
"reference_type": "TAG",
"available_references": [
"master",
"ERS-9",
"ERS-17"
]
}
Possible errors
| Http status code | Error Description |
|---|---|
| 400 | One or more of the parameters are missing or invalid |
| 403 | The instance id in the path does not match the X-Onegini-Instance header |
| 500 | Could not fetch available references by Git API |
Example error response
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request",
"error_description": "Configuration already exists"
}
Other possible responses:
| status code: | error: | error_description: |
|---|---|---|
| 400 | invalid_request | Configuration already exists |
| 400 | invalid_request | Could not find instance with given instance_id |
| 400 | invalid_request | [remote_url] field is required |
| 400 | invalid_request | Valid [authentication_type] field is required |
| 400 | invalid_request | [username] field is required |
| 400 | invalid_request | [password] field is required |
| 500 | git_api_error | Git remote repository references fetching failure: {DESCRIPTION} |
Update Configuration
This will update a single instance's configuration.
(Additional save with the selected_branch or selected_tag)
- Endpoint:
/api/v1/config/{instance_id} - Method: PATCH
- Authentication: Basic Auth or Bearer
Path parameters:
| Param | Required | Description |
|---|---|---|
instance_id |
yes | The unique identifier for a customer's application instance |
Request headers:
| Header | Required | Description |
|---|---|---|
X-Onegini-Instance |
yes | Must have the same value as the path parameter instance_id. Make sure its value is set by a trusted proxy in front of this application. It has to be a valid UUID. |
JSON body request keys:
| Param | Required | Description |
|---|---|---|
selected_reference |
yes | The selected git reference to be used when pulling. It will either be a branch or a tag based on the git_reference_type which will be tied to an environment variable. |
remote_url |
The remote url of the git repo | |
authentication_type |
Enum for the type of authentication used. Valid values: NONE, BASIC. | |
username |
depends | The username of the git repo. Required if BASIC authentication_type is selected. |
password |
depends | The password of the git repo or personal token. Required if BASIC authentication_type is selected. |
Example request Saving the selected reference:
POST /api/v1/config/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-Onegini-Instance: a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
Host: external-resources.example.com
Content-Type: application/json
{
"selected_reference": "application-1.0.0"
}
Successful response
HTTP/1.1 204 NO CONTENT
Cache-Control: no-store
Pragma: no-cache
Possible errors
| Http status code | Error Description |
|---|---|
| 400 | One or more of the parameters are missing or invalid |
| 403 | The instance id in the path does not match the X-Onegini-Instance header |
Example error response
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request",
"error_description": "Configuration does not exist"
}
| Possible issues: |
|---|
| Configuration does not exist |
selected_reference field is required |
username field is required |
password field is required |
Read Configuration
This will return a single instance_id's configuration.
- Endpoint:
/api/v1/config/{instance_id} - Request method: GET
- Authentication: Basic Auth or Bearer
Path parameters:
| Param | Required | Description |
|---|---|---|
instance_id |
yes | The unique identifier for a customer's application instance |
Request headers:
| Header | Required | Description |
|---|---|---|
X-Onegini-Instance |
yes | Must have the same value as the path parameter instance_id. Make sure its value is set by a trusted proxy in front of this application. It has to be a valid UUID. |
Example request
GET /api/v1/config/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-Onegini-Instance: a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
Host: external-resources.example.com
Successful response
JSON body response keys:
| json_key | Description |
|---|---|
remote_url |
The remote url of the git repo. |
authentication_type |
Enum for the type of authentication used. Valid values: NONE, BASIC. |
username |
The username of the git repo. Used if BASIC authentication_type is selected. |
selected_reference |
The selected git reference to be used when cloning from the repo. Should be a branch or tag identifier. |
reference_type |
Enum for the type of git reference used. TAG or BRANCH. This will be static based on an environment variable. |
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"remote_url": "https://github.com/CustomerABC/application.git",
"authentication_type": "BASIC",
"username": "CustomerABC",
"selected_reference": "application-1.0.0",
"reference_type": "TAG"
}
Possible Errors
| Http status code | Error Description |
|---|---|
| 403 | The instance id in the path does not match the X-Onegini-Instance header |
| 404 | Could not find Configuration linked to requested Instance |
| 500 | Could not fetch available references by Git API |
Error response 404
HTTP/1.1 404 NOT_FOUND
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Error response 500
HTTP/1.1 500 INTERNAL SERVER ERROR
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "git_api_error",
"error_description": "Git remote repository references fetching failure: {MESSAGE}"
}
Delete Configuration
- Endpoint:
/api/v1/config/{instance_id} - Method: DELETE
- Authentication: Basic Auth or Bearer
Path parameters:
| Param | Required | Description |
|---|---|---|
instance_id |
yes | The unique identifier for a customer's application instance |
Request headers:
| Header | Required | Description |
|---|---|---|
X-Onegini-Instance |
yes | Must have the same value as the path parameter instance_id. Make sure its value is set by a trusted proxy in front of this application. It has to be a valid UUID. |
Example request
DELETE /api/v1/config/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-Onegini-Instance: a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
Host: external-resources.example.com
Successful response
HTTP/1.1 204 NO CONTENT
Cache-Control: no-store
Pragma: no-cache
Possible errors
| Http status code | Error Description |
|---|---|
| 403 | The instance id in the path does not match the X-Onegini-Instance header |
| 404 | Could not find Configuration linked to requested Instance |
Error response
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Synchronize the resources of one configuration
- Endpoint:
/api/v1/config/{instance_id}/synchronize - Method: POST
- Authentication: Basic Auth or Bearer
Path parameters:
| Param | Required | Description |
|---|---|---|
instance_id |
yes | The unique identifier for a customer's application instance |
Request headers:
| Header | Required | Description |
|---|---|---|
X-Onegini-Instance |
yes | Must have the same value as the path parameter instance_id. Make sure its value is set by a trusted proxy in front of this application. It has to be a valid UUID. |
JSON body request keys:
| Param | Required | Description |
|---|---|---|
commit_id |
no | The id of the commit you want to synchronize. When added the system will synchronize a specified commit instead of a branch or tag. |
Example request
POST /api/v1/config/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b/synchronization HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-Onegini-Instance: a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
Host: external-resources.example.com
Successful response
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Possible errors
| Http status code | Error Description |
|---|---|
| 403 | The instance id in the path does not match the X-Onegini-Instance header |
| 404 | Could not find Configuration linked to requested Instance |
Read a list of available Git references
This endpoint returns a list of available Git reference based on the configuration for the instance.
- Endpoint:
/api/v1/reference/{instance_id} - Method: GET
- Authentication: Basic Auth or Bearer
Path parameters:
| Param | Required | Description |
|---|---|---|
instance_id |
yes | The unique identifier for a customer's application instance |
Request headers:
| Header | Required | Description |
|---|---|---|
X-Onegini-Instance |
yes | Must have the same value as the path parameter instance_id. Make sure its value is set by a trusted proxy in front of this application. It has to be a valid UUID. |
Example request
GET /api/v1/reference/a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-Onegini-Instance: a31dbf27-75d5-45c6-9acd-2fb1376d4e3b
Host: external-resources.example.com
Successful Response
JSON body response keys:
| json_key | Description |
|---|---|
result |
The available references from the git repo. It will either be a list of tags or branches depending on the environment. |
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"result": [
"master",
"ERS-9",
"ERS-17"
]
}
Possible Errors
| Http status code | Error Description |
|---|---|
| 403 | The instance id in the path does not match the X-Onegini-Instance header |
| 404 | Could not find Configuration linked to requested Instance |
| 500 | Could not fetch available references by Git API |
Error Response 404
HTTP/1.1 404 NOT_FOUND
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Error Response 500
HTTP/1.1 500 INTERNAL SERVER ERROR
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "git_api_error",
"error_description": "Git remote repository references fetching failure: {MESSAGE}"
}