API characteristics
The following sections describe important characteristics about the SecureAuth Identity Store API.
Base URL
The following base endpoint supports the Identity Store API. After you set the tenant variable, the base URL is your unique subdomain.
{{tenant}}.ids.secureauth.comExample: acme.ids.secureauth.com
Versioning
The SecureAuth Identity Store API version 1 includes support for the SCIM version 2 methods. This section also describes some other information you will see in the API paths.
The SecureAuth Identity Store publishes a versioned API that is currently at version 1 (v1). As we make major changes to the APIs or their payloads, we will increase the version. The best practice is to use the latest version; we will strive to make new versions of the API backward-compatible with prior versions.
The SecureAuth Identity Store API uses SCIM 2.0 (v2) methods. We will move to the latest SCIM version as updates fit in our release schedule so we follow the best practice of using the latest version.
The path will look like the following example when you use a SCIM method:
{{tenant}}.ids.secureauth.com/api/v1/scim/ids/{{ids_id}}/v2/Userswhere:
api/v1 defines the SecureAuth Identity Store API version; all endpoints have this in the path, whether they are SecureAuth endpoints or SCIM endpoints.
scim/ids/{{ids_id}}/v2 defines the SCIM version
{{ids_id}} refers to the identity store ID, for example: 35dcebb2-299c-432d-b6c1-881aac21e035
When you use a method that is not based on SCIM, such as GET access token, you will see the following path:
{{tenant}}.ids.secureauth.com/api/v1/privy/ids/{{ids_id}}/g3/tokenwhere:
privy is short for privilege. You will use this GET method to retrieve your access token, which reflects your privileges in the system.
/g3 refers to higher level services that SecureAuth offers, such as token provisioning.
{{ids_id}} refers to the identity store ID, for example: 35dcebb2-299c-432d-b6c1-881aac21e035
Request format
All requests must contain an Authorization header in Bearer format.
Response format
Responses are displayed in SCIM-based JSON.
Statuses
Responses are displayed in JSON and always return a status.
Successful requests contain a status of 200 OK , 201 Created , or 204 No Content in the response and are followed by a message describing what succeeded, such as Word is present, Group successfully updated, Identity Store successfully updated, etc.
Unsuccessful requests contain statuses of 400s or 500's in the response. A message will describe the reason for the failure, as shown in the following table.
Response number | Description | Guidance |
|---|---|---|
400 |
The request is malformed. | Be sure the variables are correct and the request does not contain typos. |
The specified parameter cannot be used. | Change the parameter to one that is allowed. | |
The specified object contains invalid content. | Change the content for the object. | |
401 |
The request requires certain privileges. | If you see If you should have the required privileges in the identity store, see your administrator. |
403 |
The request requires certain privileges | The user attempting the operation does not have privileges for this resource. If the user should have the required privileges for this resource, see your administrator. |
404 |
The word is not in the deny list for the | Add the word to the deny list. |
409 |
You cannot create two groups with the same name. | Give the group a unique name. |
You cannot create two identity stores with the same name. | Give the identity store a unique name. Special characters are not recognized as unique parts of the identity store name. Example: employeesusa, employees-usa, and employees usa are all seen as the same name...employeesusa. | |
You cannot create two password policies with the same name. | Give the password policy a unique name. | |
You cannot create the same user name in an identity store. | The user was already created in the identity store. Go get a cup of coffee. | |
503 |
The server cannot complete the request; the server might be overloaded or down for maintenance. | This is usually a temporary server state. Wait a minute and then try again. |
Default vs. secondary identity stores
Your organization can use one or more identity stores; however, everyone starts out with a default identity store, default. The name and ID is default. You might add more identity stores, with names of Customers and Employees, and those are secondary identity stores. Secondary identity stores are assigned a global unique identifier (GUID), such as 35dcebb2-299c-432d-b6c1-881aac21e035; you'll use the GUID in your request payloads.
The image in the following example shows the kind of information stored in the default (Acme) and secondary (Customers, Employees) identity stores.
 |
For the Identity Store API, you will notice differences in the path when sending requests for information that resides in default versus secondary identity stores. For example, when sending requests for groups, password policies, and deny lists, the request path will look like this:
{{tenant}}.ids.secureauth.com/api/v1/scim/ids/default/v2/GroupsNote
Notice that you do not need to enter an ids_id variable. This is because data for groups, password policies, and deny lists reside in the default identity store and are global. Secondary identity stores use the same global groups, password policies, and deny lists as the default identity store, so all requests for groups, password policies, and deny lists are routed automatically to the default identity store.
When sending requests for everything else, such as users and memberships, the request path will look like this:
{{tenant}}.ids.secureauth.com/api/v1/scim/ids/35dcebb2-299c-432d-b6c1-881aac21e035/v2/UsersNotice that you must enter an ids_id variable, in the form of a global unique identifier (GUID). This is because each secondary identity store keeps its own identity information, apart from the default identity store.