The following sections give you a general overview of how the SPS REST API works.
The REST server must permit password authentication to the SPS web interface. If only certificate-based authentication is permitted, see Authenticate to the SPS REST API using X.509 certificate.
To check the permitted authentication method, query the /api/authentication/types endpoint.
If the types field of the response includes the x509 object, certificate-based authentication is permitted.
If it includes only the basic object, password authentication is permitted.
If it includes both fields, then certificate-based authentication is permitted for the users, but the admin user can authenticate with password as well. Note that in this case, SPS assumes that the admin user will authenticate with a password, and expects password-authentication on the /api/authentication endpoint. To authenticate with a certificate, use the /api/authentication?type=x509 endpoint.
You can access the REST server on the same IP address and port that you use to access the SPS web interface. Note that management (administrator) access must be enabled on the interface. For details on configuring management access, see "Configuring user and administrator login addresses" in the Administration Guide.
For the user to have full access over the SPS REST API, they must have the REST server privilege. The user privileges on the web UI and REST API are synchronized. For example, if the user has the ICA Control / Connections privilege then they can access this page on the web UI and also the /api/configuration/ica/connections endpoint on the REST API.For details, see "Modifying group privileges" in the Administration Guide.
Note that the built-in api usergroup does not have this privilege by default, it is used to access the SOAP RPC API of SPS.
Note that the system time of SPS and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both SPS and most REST clients validate this. As a result, if the system time of SPS and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access SPS. (If the session_id is missing from the cookies file, check the system clocks.)
Make sure that user credentials are encoded in UTF-8.
To authenticate on the SPS REST server, send a GET request over HTTPS using the basic HTTP authentication method, including your username and password to the /api/authentication resource.
If the authentication is successful, the server returns the 200 status code, and a meta object in the response body. Also, the HTTP headers of the response include an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request.
For every subsequent request, include the session_id header with the value of the received session ID. For example:
session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5
The authenticated session times out after 20 minutes of inactivity.
Note that the system time of SPS and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both SPS and most REST clients validate this. As a result, if the system time of SPS and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access SPS. (If the session_id is missing from the cookies file, check the system clocks.)
GET https://<IP-address-of-SPS>/api/authentication
| Header name | Description | Required | Values |
|---|---|---|---|
| Authorization | Contains the username and password of the user | Required | The string Basic followed by the username:password encoded using the RFC2045-MIME. For example, Basic YWRtaW46YQ== |
The following command authenticates on SPS using the curl HTTP client. The --insecure option used in the example is used to bypass verifying the certificate of SPS. (Alternatively, you can use the --cacert option or the CURL_CA_BUNDLE environment variable to specify the Certificate Authority to verify the certificate of SPS. For details, see the curl man page).
When using the REST API in production environments, make sure to download the CA certificate of SPS from Basic Settings > Management > SSL certificate > CA X.509 certificate, and validate the certificate of SPS using this CA certificate, or with the CA certificate you used to sign the Server X.509 certificate of SPS.
curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<SPS-IP-address>/api/authentication
The cookie containing the session ID is also received (you can display it for example with the tail -l cookies command).
localhost FALSE / FALSE 1395325830 session_id 600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee
The following command retrieves the configuration of SPS, using the session ID received during the authentication.
curl --cookie cookies --insecure https://<IP-address-of-SPS>/api/configuration
The following is a sample response received if the authentication is successful.
For details of the meta object, see Message format.
{
"meta": {
"href": "/api",
"next": "/api",
"transaction": "/api/transaction"
}
}
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
| Code | Description | Notes |
|---|---|---|
| 200 | OK | Successful authentication |
| 400 | InvalidAuthenticationRequest | Unable to authenticate: no valid credentials found. |
| 401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
| 405 | MethodNotAllowed | You tried using an unsupported HTTP method. Use the GET method for authentication. |
The REST server must permit certificate authentication to the SPS web interface. If only password-based authentication is permitted, see Authenticate to the SPS REST API.
To check the permitted authentication method, query the /api/authentication/types endpoint.
If the types field of the response includes the x509 object, certificate-based authentication is permitted.
If it includes only the basic object, password authentication is permitted.
If it includes both fields, then certificate-based authentication is permitted for the users, but the admin user can authenticate with password as well. Note that in this case, SPS assumes that the admin user will authenticate with a password, and expects password-authentication on the /api/authentication endpoint. To authenticate with a certificate, use the /api/authentication?type=x509 endpoint.
You can access the REST server on the same IP address and port that you use to access the SPS web interface. Note that management (administrator) access must be enabled on the interface. For details on configuring management access, see "Configuring user and administrator login addresses" in the Administration Guide.
For the user to have full access over the SPS REST API, they must have the REST server privilege. The user privileges on the web UI and REST API are synchronized. For example, if the user has the ICA Control / Connections privilege then they can access this page on the web UI and also the /api/configuration/ica/connections endpoint on the REST API.For details, see "Modifying group privileges" in the Administration Guide.
Note that the built-in api usergroup does not have this privilege by default, it is used to access the SOAP RPC API of SPS.
Note that the system time of SPS and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both SPS and most REST clients validate this. As a result, if the system time of SPS and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access SPS. (If the session_id is missing from the cookies file, check the system clocks.)
Make sure that user credentials are encoded in UTF-8.
To authenticate on the SPS REST server, send an HTTPS GET request, including your certificate to the /api/authentication?type=x509 resource. The certificate must be signed by the Trusted CA certificate that is configured on the Users & Access Control > Settings > X.509 > AUTHENTICATION CA field of the SPS web interface, or the /api/configuration/aaa/settings resource.
If the authentication is successful, the server responds with an HTTP 302 redirect to the /api/ resource, and also , sets an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request. The response body also includes a meta object.
For every subsequent request, include the session_id header with the value of the received session ID. For example:
session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5
The authenticated session times out after 20 minutes of inactivity.
Note that the system time of SPS and the client must be synchronized. The authentication cookie is valid for twenty minutes, and both SPS and most REST clients validate this. As a result, if the system time of SPS and the client is significantly different from each other, the authentication seems to be successful, but you will not be able to actually access SPS. (If the session_id is missing from the cookies file, check the system clocks.)
GET https:<IP-address-of-SPS>/api/authentication
| Header name | Description | Required | Values |
|---|---|---|---|
| Authorization | Contains the username and password of the user | Required | The string Basic followed by the username:password encoded using the RFC2045-MIME. For example, Basic YWRtaW46YQ== |
The following command authenticates on SPS using the curl HTTP client. The --insecure option used in the example is used to bypass verifying the certificate of SPS. (Alternatively, you can use the --cacert option or the CURL_CA_BUNDLE environment variable to specify the Certificate Authority to verify the certificate of SPS. For details, see the curl man page).
When using the REST API in production environments, make sure to download the CA certificate of SPS from Basic Settings > Management > SSL certificate > CA X.509 certificate, and validate the certificate of SPS using this CA certificate, or with the CA certificate you used to sign the Server X.509 certificate of SPS.
curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<SPS-IP-address>/api/authentication
The cookie containing the session ID is also received (you can display it for example with the tail -l cookies command).
localhost FALSE / FALSE 1395325830 session_id 600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee
The following command retrieves the configuration of SPS, using the session ID received during the authentication.
curl --cookie cookies --insecure https://<IP-address-of-SPS>/api/configuration
The following is a sample response received if the authentication is successful.
For details of the meta object, see Message format.
{
"meta": {
"href": "/api",
"next": "/api",
"transaction": "/api/transaction"
}
}
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
| Code | Description | Notes |
|---|---|---|
| 302 | OK | Successful authentication. If the authentication is successful, the server returns the 302 status code, and a meta object in the response body. Also, the HTTP headers of the response include an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request. The Location header in the response is /api/. |
| 400 | InvalidAuthenticationRequest | Unable to authenticate: no valid credentials found. SPS returns this message if password fallback is enabled for the admin user, but the admin tries to authenticate with a certificate on the /api/authentication endpoint. To authenticate with a certificate, use the /api/authentication?type=x509 endpoint. |
| 401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
| 405 | MethodNotAllowed | You tried using an unsupported HTTP method. Use the GET method for authentication. |
You can check the endpoints and methods that a particular user is authorized to access.
The user must be logged in.
GET https:<IP-address-of-SPS>/api/user_info
| Cookie name | Description | Required | Values |
|---|---|---|---|
| session_id | Contains the authentication token of the user | Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the SPS REST API. Note that this session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
The following command retrieves user information from SPS about the logged in user, using the session ID received during the authentication.
curl --cookie cookies https://<IP-address-of-SPS>/api/user_info
This information is also available on the /api/user/info and /api/userinfo endpoints.
The following is a sample response received if the request to retrieve user information is successful.
For details of the meta object, see Message format.
{
"user": {
"name": "admin",
}
"endpoints": [
{
"methods": [
"DELETE",
"GET",
"POST",
"PUT"
],
"url": "/api"
},
{
"...": "..."
}
],
"meta": {
"href": "/api/user_info",
"...": "..."
}
}
| Element | Type | Description | |
|---|---|---|---|
| user | Top-level element, contains the details of the user whose access rights information has been retrieved. | ||
| name | string | The username of the logged-in user whose information has been retrieved. | |
| endpoints | Top-level element, contains the details of the endpoints that the user is authorized to access. | ||
| methods | string |
The methods that user is authorized to use, and the permitted HTTP method (for example, GET, POST) for each endpoint. This information is also available on the /api/endpoints endpoint. | |
| url | string | The resource that the user is authorized to access. | |
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
| Code | Description | Notes |
|---|---|---|
| 200 | OK | User information has been retrieved successfully. |
| 401 | Unauthenticated | The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 403 | Unauthorized | The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
© 2024 One Identity LLC. ALL RIGHTS RESERVED. Terms of Use Privacy Cookie Preference Center