On This Page
ASA Service Users API
Get started
The Advanced Server Access (ASA) API is logically separate from the rest of the Okta APIs and uses a different API namespace:
https://app.scaleft.com/v1/
Advanced Server Access (ASA) Service Users are used to access the ASA API. ASA Service Users are provided tokens for authentication and authorization against the service.
Explore the Service Users API: 
(opens new window).
Service Users API operations
The Service Users API has the following operations:
- Issue a Service User token
- Lists the Service Users for a Team
- Create a Service User
- Fetch a Service User
- Update the status of a Service User
- List the API keys for a Service User
- Rotate API keys for a Service User
- Delete an API key for a Service User
Issue a Service User token
POST https://app.scaleft.com/v1/teams/${team_name}/service_token
Most calls to the Okta Advanced Server Access API require an HTTP Authorization header with a value of Bearer ${AUTH_TOKEN}.
To retrieve an auth token, you need to create a Service User and API key (opens new window), then pass the API key information to this endpoint.
Auth tokens may expire at any time, so code that uses them should be prepared to handle a 401 response code by creating a new auth token.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
team_name | string | The name of your Team |
Request query parameters
This endpoint has no query parameters.
Request body
This endpoint requires an object with the following fields.
| Properties | Type | Description |
|---|---|---|
key_id | string | The ID of the API key |
key_secret | string | The secret associated with the API key |
Response body
This endpoint returns an object with the following fields and a 200 code on a successful call.
| Properties | Type | Description |
|---|---|---|
bearer_token | string | The JSON Web Token used to authenticate against the ASA API |
expires_at | string | The time at which the token expires, formatted in accordance with RFC 3339 (opens new window) |
team_name | string | The name of the Team this token is for |
Usage example
Request
curl -v -X POST \
-H "Authorization: Bearer ${jwt}" \
--data '{
"key_id": "6052868b-1b04-4a14-8288-e6496d7f2f4b",
"key_secret": "uF0SoVBVQP/hJmQSLUZdM2a7ArYzjD8ykzvG7n4tKaOEfSErcwMUUDWpEf4Q42/HaVKPZUfILkzy/bsQFv7WRg=="
}' \
https://app.scaleft.com/v1/teams/${team_name}/service_token
Response
{
"bearer_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImI4YTAzODA0MTM0NjctNGU5OC04ZDU2LTAxNDRlNGNkMGViMCIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzY4MTE1OTAsImlzcyI6InNjYWxlZnQuYXV0aC50b2tlbiIsImp0aSI6IjA0YjRhNTE4LWU5YzYtNDc1My05YWY4LThlOTAwNjVjNjX5YSIsInJvbGVzIjp7IjE0NzY4MTE1OTAiOm51bGx9LCJ0ZWFtIjoic2NhbGVmdCIsInVzZXIiOiJyb2JvdF9ydXNzZWxsIn0.pHuv06Q1-sKjHrGXUzQi-uM7AAG3K1Q6rpuxycR2Py6QHwLrto1uZmZt4wrBo6tQRCl3RjHBKGcDmEfBZ6_gFnckpFMkIXUT3sIDmOvSACthgprcXjfYh0KarEDmDnIMsEPl7FVhl4N_I0yLK9O5XSS07AvAc-7RRD8udpo7inIDTRCCEvoJ16osgL1IzoDvc7ZPDj8-xhJ_kAsKc-vJ5WYKLAlCFx_fixayM43Apg2TySNE5nSeJFCa02F4ViZleY7K2l4h_p143DzVZjWEBeKmyQVRXhbZzL6HwONQckhgp_LHuSrP_sOtVc7BrFwmZq2NZtXEOWyQWfJ4Yp0qg8NzV2LhKLc4LncpQuagf8OA8jyEeQwbu3Rq9zp0y-FodMg64qfWcPSu53HiwYC9dvgw5zhXa8zuZRcPMO_orCPVYnmO761xAfsp-P8aJJZDqpxlzKA0s-ClRsgunC5C9Xq5snIq-f4hT45u8ldBfAr6dLkDO8BdPMTzufH52bTWX3iJ1ipW1YqMefJhPMzBHLwnJ3SYWN7WTEuRyoC6ndQ60PcEzsPJYAO5MxdY4WsnYOqv3aIryuTlwW3K0dNqcvBSirgxv5X7AvidO-JQLSXXrY134BxgyLBze7FwVYwH7ZhzBdX-DwsUwQsJ7R0mRWxpNnhGu7NjkbB0-QJs",
"expires_at": "2016-10-18T17:26:30Z",
"team_name": "scaleft"
}
Lists the Service Users for a Team
GET https://app.scaleft.com/v1/teams/${team_name}/service_users
Lists all the Service Users for a Team
This endpoint requires the access_admin role.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
team_name | string | The name of your Team |
Request query parameters
| Parameter | Type | Description |
|---|---|---|
contains | string | (Optional) Includes ASA Users with name that contains the value |
count | number | (Optional) The number of objects per page |
descending | boolean | (Optional) The object order |
include_service_users | string | (Optional) Include Service Users in the results |
offset | string | (Optional) The UUID of the object used as an offset for pagination |
prev | boolean | (Optional) The direction of paging |
starts_with | string | (Optional) Includes ASA Users with name that begins with the value |
status | string | (Optional) Includes ASA Users with specified statuses. Valid statuses: ACTIVE, DISABLED, and DELETED. |
Request body
This endpoint has no request body.
Response body
This endpoint returns a list of objects with the following fields and a 200 code on a successful call.
| Properties | Type | Description |
|---|---|---|
deleted_at | string | The time at which the ASA User was deleted |
details | object | An object with the following keys, the values of which are all strings: first_name, last_name, full_name, email. |
id | string | The UUID of the ASA User |
name | string | The username of the ASA User |
oauth_client_application_id | string | The ID of the ASA User provided by OAuth, if it exists |
role_grants | array | The permission roles available to the ASA User |
status | string | Status of the ASA User: ACTIVE, DISABLED, or DELETED. ASA Users can't disable or delete their own ASA User. |
user_type | string | The type of ASA User: service or human |
Usage example
Request
curl -v -X GET \
-H "Authorization: Bearer ${jwt}" \
https://app.scaleft.com/v1/teams/${team_name}/service_users
Response
{
"list": [
{
"deleted_at": null,
"details": null,
"id": "aa225c16-af6e-4ab4-9150-456fd472e2d7",
"name": "shreve",
"oauth_client_application_id": null,
"role_grants": null,
"status": "ACTIVE",
"user_type": "service"
},
{
"deleted_at": null,
"details": null,
"id": "6b69de4e-90be-4016-9085-d54bf5815da1",
"name": "dilsey.gibson",
"oauth_client_application_id": null,
"role_grants": null,
"status": "DISABLED",
"user_type": "service"
}
]
}
Create a Service User
POST https://app.scaleft.com/v1/teams/${team_name}/service_users
Creates a Service User that can be used to automate interaction with the Advanced Server Access API
This endpoint requires the access_admin role.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
team_name | string | The name of your Team |
Request query parameters
This endpoint has no query parameters.
Request body
This endpoint requires an object with the following fields.
| Properties | Type | Description |
|---|---|---|
name | string | The name of the Service User |
Response body
This endpoint returns an object with the following fields and a 201 code on a successful call.
| Properties | Type | Description |
|---|---|---|
deleted_at | string | The time at which the ASA User was deleted |
details | object | An object with the following keys, the values of which are all strings: first_name, last_name, full_name, email. |
id | string | The UUID of the ASA User |
name | string | The username of the ASA User |
oauth_client_application_id | string | The ID of the ASA User provided by OAuth, if it exists |
role_grants | array | The permission roles available to the ASA User |
status | string | Status of the ASA User: ACTIVE, DISABLED, or DELETED. ASA Users can't disable or delete their own ASA User. |
user_type | string | The type of ASA User: service or human |
Usage example
Request
curl -v -X POST \
-H "Authorization: Bearer ${jwt}" \
--data '{
"name": "shreve"
}' \
https://app.scaleft.com/v1/teams/${team_name}/service_users
Response
{
"deleted_at": null,
"details": null,
"id": "aa225c16-af6e-4ab4-9150-456fd472e2d7",
"name": "shreve",
"oauth_client_application_id": null,
"role_grants": null,
"status": "ACTIVE",
"user_type": "service"
}
Fetch a Service User
GET https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}
Fetches information regarding a specific Service User
This endpoint requires the access_admin role.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
team_name | string | The name of your Team |
user_name | string | The relevant username |
Request query parameters
This endpoint has no query parameters.
Request body
This endpoint has no request body.
Response body
This endpoint returns an object with the following fields and a 200 code on a successful call.
| Properties | Type | Description |
|---|---|---|
deleted_at | string | The time at which the ASA User was deleted |
details | object | An object with the following keys, the values of which are all strings: first_name, last_name, full_name, email. |
id | string | The UUID of the ASA User |
name | string | The username of the ASA User |
oauth_client_application_id | string | The ID of the ASA User provided by OAuth, if it exists |
role_grants | array | The permission roles available to the ASA User |
status | string | Status of the ASA User: ACTIVE, DISABLED, or DELETED. ASA Users can't disable or delete their own ASA User. |
user_type | string | The type of ASA User: service or human |
Usage example
Request
curl -v -X GET \
-H "Authorization: Bearer ${jwt}" \
https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}
Response
{
"deleted_at": null,
"details": null,
"id": "6b69de4e-90be-4016-9085-d54bf5815da1",
"name": "dilsey.gibson",
"oauth_client_application_id": null,
"role_grants": null,
"status": "ACTIVE",
"user_type": "service"
}
Update the status of a Service User
PUT https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}
Updates information about a specific Service User
This endpoint requires the access_admin role.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
team_name | string | The name of your Team |
user_name | string | The relevant username |
Request query parameters
This endpoint has no query parameters.
Request body
This endpoint requires an object with the following fields.
| Properties | Type | Description |
|---|---|---|
deleted_at | string | The time at which the ASA User was deleted |
details | object | An object with the following keys, the values of which are all strings: first_name, last_name, full_name, email. |
id | string | The UUID of the ASA User |
name | string | The username of the ASA User |
oauth_client_application_id | string | The ID of the ASA User provided by OAuth, if it exists |
role_grants | array | The permission roles available to the ASA User |
status | string | Status of the ASA User: ACTIVE, DISABLED, or DELETED. ASA Users can't disable or delete their own ASA User. |
user_type | string | The type of ASA User: service or human |
Response body
This endpoint returns an object with the following fields and a 200 code on a successful call.
| Properties | Type | Description |
|---|---|---|
deleted_at | string | The time at which the ASA User was deleted |
details | object | An object with the following keys, the values of which are all strings: first_name, last_name, full_name, email. |
id | string | The UUID of the ASA User |
name | string | The username of the ASA User |
oauth_client_application_id | string | The ID of the ASA User provided by OAuth, if it exists |
role_grants | array | The permission roles available to the ASA User |
status | string | Status of the ASA User: ACTIVE, DISABLED, or DELETED. ASA Users can't disable or delete their own ASA User. |
user_type | string | The type of ASA User: service or human |
Usage example
Request
curl -v -X PUT \
-H "Authorization: Bearer ${jwt}" \
--data '{
"deleted_at": null,
"details": null,
"id": "6b69de4e-90be-4016-9085-d54bf5815da1",
"name": "dilsey.gibson",
"oauth_client_application_id": null,
"role_grants": null,
"status": "DISABLED",
"user_type": "service"
}' \
https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}
Response
{
"deleted_at": null,
"details": null,
"id": "6b69de4e-90be-4016-9085-d54bf5815da1",
"name": "dilsey.gibson",
"oauth_client_application_id": null,
"role_grants": null,
"status": "DISABLED",
"user_type": "service"
}
List the API keys for a Service User
GET https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}/keys
Lists the API keys that belong to a specific Service User. The corresponding secret for each key isn't provided.
This endpoint requires the access_admin role.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
team_name | string | The name of your Team |
user_name | string | The relevant username |
Request query parameters
This endpoint has no query parameters.
Request body
This endpoint has no request body.
Response body
This endpoint returns a list of objects with the following fields and a 200 code on a successful call.
| Properties | Type | Description |
|---|---|---|
expires_at | string | The expiration time of the key |
id | string | The UUID of the API key |
issued_at | string | The time at which the key was issued |
last_used | string | The last time the key was used against Advanced Server Access |
Usage example
Request
curl -v -X GET \
-H "Authorization: Bearer ${jwt}" \
https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}/keys
Response
{
"list": [
{
"expires_at": "0001-01-01T00:00:00Z",
"id": "c6de9d40-1e6c-4033-88cb-992367d162eb",
"issued_at": "2020-04-07T02:00:00Z",
"last_used": null
},
{
"expires_at": "2020-04-09T00:00:00Z",
"id": "f37fadfc-fa03-4f46-a390-ce202772cff4",
"issued_at": "2020-04-07T00:00:00Z",
"last_used": null
}
]
}
Rotate API keys for a Service User
POST https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}/keys
Rotates API keys for a Service User. Rotating an API key automatically sets an expiration date for the rest of the API keys that a Service User has.
This endpoint requires the access_admin role.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
team_name | string | The name of your Team |
user_name | string | The relevant username |
Request query parameters
This endpoint has no query parameters.
Request body
This endpoint has no request body.
Response body
This endpoint returns an object with the following fields and a 200 code on a successful call.
| Properties | Type | Description |
|---|---|---|
expires_at | string | The expiration time of the key |
id | string | The UUID of the API key |
issued_at | string | The time at which the key was issued |
last_used | string | The last time the key was used against Advanced Server Access |
secret | string | The secret of the API key. This is used to authenticate the Service User. Don't share. |
Usage example
Request
curl -v -X POST \
-H "Authorization: Bearer ${jwt}" \
https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}/keys
Response
{
"expires_at": "0001-01-01T00:00:00Z",
"id": "ba7ffbe9-c8e4-45c9-bc07-45729711c952",
"issued_at": "2020-04-07T00:00:00Z",
"last_used": null,
"secret": "NOvsvBg0g9mFXdHbLxEJcEFpu+LZjQSKsYezqMALq5WbGZTpUsxoS4vBqqHOO9O3xrhOq03B+oLf7bSTShbudw=="
}
Delete an API key for a Service User
DELETE https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}/keys/${key_id}
Deletes an API key and prevents its future use
This endpoint requires the access_admin role.
Request path parameters
| Parameter | Type | Description |
|---|---|---|
key_id | string | The UUID of the Service User key |
team_name | string | The name of your Team |
user_name | string | The relevant username |
Request query parameters
This endpoint has no query parameters.
Request body
This endpoint has no request body.
Response body
This endpoint returns a 204 No Content response on a successful call.
Usage example
Request
curl -v -X DELETE \
-H "Authorization: Bearer ${jwt}" \
https://app.scaleft.com/v1/teams/${team_name}/service_users/${user_name}/keys/${key_id}
Response
HTTP 204 No Content