The REST API for STA provides programmatic access to the following management and logging functions of STA:

• Account information API allows service providers to retrieve service information for their managed accounts, including details such as the organization name, account status, account type, and subscription plan.

• Application management API allows you to integrate STA application management with your existing Identity Governance and Administration (IGA) systems.

• Application template management API allows you to read the list of available application templates.

• Diagnostics API allows you to validate your API key and permissions, and to check the health of the REST API for STA. Developers can add a health check to their code to make sure that STA is good before making another call.

• Group management API allows you to create, read, update and delete groups, and to change group membership.

• Home API allows you to open the API documentation in a browser.

• Logs API allows you to retrieve access and authentication logs. You can store the logs on a Security Information and Event Management (SIEM) system, local repository, or syslog file server. You can retrieve the logs only for the account that is associated with the API key, or for a direct or delegated child of that account.

• User management API allows you to integrate STA user management into your existing user management workflows that don't rely on synchronizing a user store. It includes methods for creating, reading, updating, and deleting users in STA. It includes methods for terminating user sessions, so that you can monitor the active user sessions and terminate them on request. It also includes methods for managing authenticators.

STA also includes a SCIM API that allows you to connect a user repository that supports outbound SCIM directly to STA, and use the SCIM protocol to provision users into STA.

Limitations

• The number of users that can be created with the REST API is directly related to the capacity that is assigned to a virtual server. In other words, if you license 100 users, you can create 100 users with the API, regardless of whether they are internal or external users.

  This is different from the STA Token Management console, where internal users without tokens are not counted as users that need a license.

• The user name is limited to 64 characters.

• Groups cannot be renamed when they are assigned to a token provisioning rule or operator role provisioning rule.

• There are several limitations on managing authenticators.

Getting started with the REST API for STA

Before you can use the REST API for STA, you need to get the following information from the STA consoles: 

• API key for authentication

• Endpoint URL to access the APIs

• Tenant code for your virtual server or account

• API documentation that describes the endpoints, methods, requests, and responses

Pagination

Pagination in the REST API for STA is the process of separating the results into pages and adding consecutive numbers to identify the sequential order of pages. It helps to limit the number of results to minimize response times for large data sets and responses. Requests that return a list of resources, such as the GET methods, support query parameters to handle paging through the response data.

The query parameters for pagination are:

• pageIndex: Specifies the index of the page that you want to return as an integer that starts at 0. For example, page one has index 0 and page n has index n-1.

• pageSize: Specifies the number of records to return in one request. To retrieve a large number of records, you can make multiple API requests and then combine the results within your application.

Rate limiting

In the case of rate limiting, the following response is returned:

429 Too Many Requests

The header indicates:

RateLimit-Reset: 47

This is the amount of seconds until the rate limiting resets, which is the minimum wait time.

In addition, the current thresholds and remaining calls are always included in the response:

X-RateLimit-Limit-minute
X-RateLimit-Limit-second
X-RateLimit-Remaining-minute
X-RateLimit-Remaining-second