Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The OAuth Management API provides routes for:
managing the primary OAuth client
creating and managing secondary OAuth clients
During initial onboarding for the Integration API, iownit creates your OAuth client for your primary integration with the iownit platform. If you have multiple back-office apps that need to integrate with the platform, you will need to create secondary OAuth clients. These clients are linked to the same organization and are managed by the primary OAuth client. Secondary clients usually perform a subset of tasks and, therefore, require a smaller access scope.
The OAuth scope required for each endpoint in the Integration API is included in the description for each endpoint.
To find the required scope for an endpoint in the json file:
Access the underlying json file in Swagger.
You can do this by clicking the link in the upper right corner of the Swagger display.
Download the JSON file.
Open the file in an editor that parses the JSON.
For example, you can use editor.swagger.io.
Locate the endpoint of interest.
Scroll to the security section of the endpoint spec. The scope is listed under oauth2.
This route is used to create a new OAuth client. This new client will be linked to the same organization as the client that is making the current request.
This route will typically be used by the primary OAuth client of the organization to register other clients to be used by different back-office apps to execute a subset of actions.
This endpoint can be called by applications with access to scope "manageExternalClients".
The password of this OAuth client
u7/JvJ+:X?Wc]6}.The name of application that this client is associated with.
TEST1234 AppPOST /external/v1/oauth/client HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 181
{
"extraData": {
"externalId": "123456789",
"some": "Custom Property"
},
"accessScopes": [
"createSubscription",
"readSubscription"
],
"password": "u7/JvJ+:X?Wc]6}.",
"application": "TEST1234 App"
}{
"extraData": {
"externalId": "123456789",
"some": "Custom Property"
},
"clientId": "TEST1234",
"accessScopes": [
"createSubscription",
"readSubscription"
],
"application": "TEST1234 App"
}This route is used to update an existing OAuth client.
This route would typically be used to grant or revoke access scopes to a specific client.
This endpoint can be called by applications with access to scope "manageExternalClients".
The unique identifier of the OAuth client. Must be alphanumeric
TEST1234Pattern: ^[a-zA-Z0-9-]*$The name of application that this API client is associated with.
TEST1234 AppPUT /external/v1/oauth/client HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 173
{
"extraData": {
"externalId": "123456789",
"some": "Custom Property"
},
"clientId": "TEST1234",
"accessScopes": [
"createSubscription",
"readSubscription"
],
"application": "TEST1234 App"
}No content
This route is used by the primary OAuth client to set a new password for other clients.
This route will typically be used an OAuth client loses their password.
This endpoint can be called by applications with access to scope "manageExternalClients".
The password of this OAuth client
u7/JvJ+:X?Wc]6}.The unique identifier of the OAuth client. Must be alphanumeric
TEST1234Pattern: ^[a-zA-Z0-9-]*$PUT /external/v1/oauth/client/password-reset HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53
{
"password": "u7/JvJ+:X?Wc]6}.",
"clientId": "TEST1234"
}No content
This route is to be used by an OAuth client to get its own information. The client should be authenticated and a valid access token provided.
GET /external/v1/oauth/client/current HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"extraData": {
"externalId": "123456789",
"some": "Custom Property"
},
"clientId": "TEST1234",
"accessScopes": [
"createSubscription",
"readSubscription"
],
"application": "TEST1234 App"
}This route is to be used by an OAuth client to update its own password. The client should be authenticated and a valid access token provided.
The password of this OAuth client
u7/JvJ+:X?Wc]6}.PUT /external/v1/oauth/password HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31
{
"password": "u7/JvJ+:X?Wc]6}."
}No content
This route is to be used by an OAuth client to get all the OAuth clients that are linked to the same organization as the current client. The client should be authenticated and a valid access token provided.
This endpoint can be called by applications with access to scope "manageExternalClients".
GET /external/v1/oauth/client HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
{
"extraData": {
"externalId": "123456789",
"some": "Custom Property"
},
"clientId": "TEST1234",
"accessScopes": [
"createSubscription",
"readSubscription"
],
"application": "TEST1234 App",
"primary": true
}
]This route is used by the primary OAuth client to remove an existing OAuth client.
This route would typically be used to remove a client because the underlying app has been compromised or has been decommissioned and the client has no further usages.
This endpoint can be called by applications with access to scope "manageExternalClients".
The unique identifier of the OAuth client being removed
USS3JKS01I00DELETE /external/v1/oauth/client/{clientId} HTTP/1.1
Host:
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
No content