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.com

Example: 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/Users

where:

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/token

where:

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 500s in the response. A message will describe the reason for the failure, as shown in the following table.

Response number

Description

Guidance

400

Bad Request

The request is malformed.

Be sure the variables are correct and the request does not contain typos.

Bad input parameter

The specified parameter cannot be used.

Change the parameter to one that is allowed.

Invalid input, object invalid

The specified object contains invalid content.

Change the content for the object.

401

Unauthorized

The request requires certain privileges.

If you see Invalid Token then the access token has timed out; request another access token.

If you should have the required privileges in the identity store, see your administrator.

403

Forbidden

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

Word is not present

The word is not in the deny list for the deny_id you searched.

Add the word to the deny list.

409

An existing group already exists

You cannot create two groups with the same name.

Give the group a unique name.

The identity store already exists

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.

The password policy already exists

You cannot create two password policies with the same name.

Give the password policy a unique name.

An existing user already exists

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

Service unavailable

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.

default_secondary_ids_info.png

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/Groups

Note

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/Users

Notice 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.