Session Management

Identity Providers

Identity Providers are sources of user accounts. Customers have a local identity provider which is a part of the Instart service. This is currently the only user identity source supported.

GET /idps

Returns an enumerable list of identity sources which have been configured for the customer account.

Response Messages

HTTP Status CodeResponse Model
200If the page of identity sources was returned
401If authentication of the request failed
default

Schema

{
  "total": 0,
  "page_index": 0,
  "has_more": true,
  "next_uri": "string",
  "uri": "string",
  "items": [
    {
      "id": "string",
      "uri": "string"
    }
  ],
  "prev_uri": "string"
}

GET /idps/{source_id}

Get the configuration for an identity source, a source of user accounts for the customer.

Parameters

ParameterDescriptionParameter TypeData Type
source_idThe ID of the identity sourcepathstring

Response Messages

HTTP Status CodeResponse Model
200If the identity source is returned
401If authentication of the request failed
404If no identity source with the given ID was found
default

Schema

{
  "configuration": "Map",
  "id": "string",
  "uri": "string"
}

Roles

Roles define a set of operations which users are permitted to perform. Each user is assigned a role in order to access the management services and will be limited to performing the operations allowed by that role.

GET /roles

Retrieve the list of available roles. Returns an enumerable, paged collection of roles.

Parameters

ParameterDescriptionParameter TypeData Type
pageWhich page in the enumerable list of paged results to returnqueryinteger
countThe number of roles in each page of the resultsqueryinteger

Response Messages

HTTP Status CodeResponse Model
200If the page of roles was returned
400If there was a bad query parameter provided
401If the authentication token is not valid
default

Schema

{
  "total": 0,
  "page_index": 0,
  "has_more": true,
  "next_uri": "string",
  "uri": "string",
  "items": [
    {
      "id": "string",
      "uri": "string"
    }
  ],
  "prev_uri": "string"
}

GET /roles/{role_id}

Gets the details of a specific role. Returns a model representing one of the roles available to your customer account.

Parameters

ParameterDescriptionParameter TypeData Type
role_idThe ID of the rolepathstring

Response Messages

HTTP Status CodeResponse Model
200If the role was returned
401If the authentication token was not valid
404If no role with the given ID exists.
default

Schema

{
  "name": "string",
  "id": "string",
  "uri": "string"
}

Sessions

Provides long-term login support without repeating user credentials. Sessions can be created using other forms of credentials, such as HTTP Basic authentication. The session can be set by the server as a cookie value which should be repeated by the client for subsequent requests. Sessions can be used as a substitute for credentials once created and for as long as they remain active, and therefore should be kept secret.

POST /sessions

Creates a new session. Logs a user into the system. In order to create a new session, user must provide credentials in the request header with 'Authorization' as the key and 'username:password' as the value, with of course the appropriate username and password substituted for the placeholders.

The ID of the session value obtained in response can be used as a cookie value with name "authtoken" to authenticate to future requests.

The session will remain valid up to a maximum period of one day. A session will cease to be valid if it is not used to issue a request for more than 30 minutes. A session can be deleted to render it unusable immediately.

Response Messages

HTTP Status CodeResponse Model
201If a new session was created successfully
401If authentication failed
default

Model Schema

{
  "expires": "2018-03-05T22:34:09.547Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

GET /sessions/current

Returns information about the session being used to authenticate the current request. This will return session information about whatever session is being used to make this request. If the request is not authenticated, or is not authenticated using a session, then no session will be found. No session can be found if a session token is provided which references a session that does not exist.

Response Messages

HTTP Status CodeResponse Model
201If the session information was found and returned
404If there is no current valid session
default

Schema

{
  "expires": "2018-03-05T22:34:09.547Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

PUT /sessions/current

Updates session information. This also has the effect of keeping the session alive. The ID of the session model provided will be used to update the current session in use to the session with that ID. This has the effect of setting or changing the value of the session token cookie which acts to authenticate future requests using the session. 

After a session is created, a user agent which supports cookies can update the "current" session with this API using the new session which was created so that the server sets the necessary cookies. Then, if the user agent sends the cookies back in subsequent requests, those requests will be session-authenticated.

Parameters

ParameterDescriptionParameter TypeData Type
sessionThe session model which provides updated informationbody

{
  "expires": "2018-03-05T22:34:09.521Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

Response Messages

HTTP Status CodeResponse Model
200If the update succeeded
400If the session JSON was invalid or the ID of the session to update does not exist
401If the authentication failed
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "expires": "2018-03-05T22:34:09.547Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

DELETE /sessions/current

Deletes the current session. This effectively "logs out" the user of the session so that it cannot be used anymore. When using this request, the cookie value which stores the session token is also unset so that future requests will no longer automatically be authenticated using the session when using a user agent which supports cookies. 

Response Messages

HTTP Status CodeResponse Model
204If the deletion succeeded
404If no session was used to authenticate the request
defaultSuccess

GET /sessions/{session_id}

Retrieves the information for a given session.

Parameters

ParameterDescriptionParameter TypeData Type
session_idThe ID of the sessionpathstring

Response Messages

HTTP Status CodeResponse Model
200If the session information is found and returned
404If the requested session does not exist
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "expires": "2018-03-05T22:34:09.547Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

PUT /sessions/{session_id}

Updates session information. Currently no single parameter of a session can be explicitly set. However, performing a session update is a semantically obvious way to perform a "keep-alive" request, as it will update the last access time for the session. This will update session information for whatever session is being used to make this request. If the
request is not authenticated or is not authenticated using a session then no session will be found. No session can be found if a session token is provided which references a session that does not exist.

Parameters

ParameterDescriptionParameter TypeData Type
session_idThe ID of the session to updatepathstring
sessionModelThe JSON object which provides the updated informationbody{
  "expires": "2018-03-05T22:34:09.521Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

Response Messages

HTTP Status CodeResponse Model
200If the update succeeded
400If the update JSON was invalid
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "expires": "2018-03-05T22:34:09.563Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

DELETE /sessions/{session_id}

Deletes a session. This prevents it from being used as a valid authentication token for future requests. This effectively "logs out" the session in question.

Parameters

ParameterDescriptionParameter TypeData Type
session_idThe ID of the session to deletepathstring
sessionModelThe JSON object which provides the updated informationbody{
  "expires": "2018-03-05T22:34:09.521Z",
  "id": "string",
  "uri": "string",
  "user": {
    "id": "string",
    "uri": "string"
  }
}

Response Messages

HTTP Status CodeResponse Model
204If the deletion succeeded
404If the session being deleted does not exist
defaultSuccess

Users

User resources represent the user accounts in the system. Users may be listed, created, removed, or modified. Each user also has child resources which represent their password settings and two-factor authentication. A user may modify their own password and two-factor authentication resources, but cannot affect another user's. Administrators may impose password resets on other users.

GET /users

Returns a pageable list of users for the customer account. The given count parameter will determine how many users are in each page, and the page parameter will determine which page is returned.

Parameters

ParameterDescriptionParameter TypeData Type
page

The index of the page to return

queryinteger
countThe number of users to include in each pagequeryinteger

Response Messages

HTTP Status CodeResponse Model
200If a page of users is found and returned
400If the query string parameters are not valid
401If the authentication token is not valid
403If the issuer of the request is not authorized to view users
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "has_more": true,
  "uri": "string",
  "items": [
    {
      "full_name": "string",
      "role": {
        "id": "string",
        "uri": "string"
      },
      "otp_uri": "string",
      "password_uri": "string",
      "phone_number": "string",
      "id": "string",
      "source": {
        "id": "string",
        "uri": "string"
      },
      "uri": "string",
      "otp_enabled": true,
      "email": "string",
      "enabled": true,
      "username": "string"
    }
  ]
}


POST /users

Creates a new user account. Using the identity source "local", this will create a local user account with account information stored in the customer account. For a non-local source, this will register a remote user and associate a role with the user.

Parameters

ParameterDescriptionParameter TypeData Type
userThe JSON object which provides the user informationbody{
  "full_name": "string",
  "role": {
    "id": "string",
    "uri": "string"
  },
  "otp_uri": "string",
  "password_uri": "string",
  "phone_number": "string",
  "id": "string",
  "source": {
    "id": "string",
    "uri": "string"
  },
  "uri": "string",
  "otp_enabled": true,
  "email": "string",
  "enabled": true,
  "username": "string"
}

Response Messages

HTTP Status CodeResponse Model
201If the user was created
400If the provided user JSON object was invalid
401If the authentication failed
403If the issuer of the request is not authorized to create users
defaultSuccess; JSON returned in form of user schema shown above

GET /users/{user_id}

Returns the detailed information about a user account. For a local user account, user information is included. If the user account is not local (from a remote identity source), only a role association is included.

Parameters

ParameterDescriptionParameter TypeData Type
user_idThe user IDpathstring

Response Messages

HTTP Status CodeResponse Model
200If the user account is returned
401If authentication failed
403If the issuer of the request is not authorized to view users
404
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "has_more": true,
  "uri": "string",
  "items": [
    {
      "full_name": "string",
      "role": {
        "id": "string",
        "uri": "string"
      },
      "otp_uri": "string",
      "password_uri": "string",
      "phone_number": "string",
      "id": "string",
      "source": {
        "id": "string",
        "uri": "string"
      },
      "uri": "string",
      "otp_enabled": true,
      "email": "string",
      "enabled": true,
      "username": "string"
    }
  ]
}

PUT /users/{user_id}

Update a user account. For local accounts, this will change the user details and role association of the user. For remote accounts (those from a remote identity source), only the role may be changed. Passwords must be updated through the separate password change API.

Parameters

ParameterDescriptionParameter TypeData Type
user_idThe user IDpathstring
userThe JSON object which provides the new user informationbody{
  "full_name": "string",
  "role": {
    "id": "string",
    "uri": "string"
  },
  "otp_uri": "string",
  "password_uri": "string",
  "phone_number": "string",
  "id": "string",
  "source": {
    "id": "string",
    "uri": "string"
  },
  "uri": "string",
  "otp_enabled": true,
  "email": "string",
  "enabled": true,
  "username": "string"
}
authentication
body{
  "principal": "Object",
  "authenticated": true,
  "credentials": "Object",
  "details": "Object",
  "authorities": [
    "?"
  ]
}

Response Messages

HTTP Status CodeResponse Model
200If the update was successful
400If the provided user JSON object was not valid
401If authentication failed
403If the issuer of the request is not authorized to modify users
404If the given user could not be found
defaultSuccess; JSON returned in form of user schema shown above

DELETE /users/{user_id}

Deletes a user. When deleting a user in the local identity source, the user information is removed completely. When deleting a user from a remote identity source, the role assocation for that user is removed (this API does not manage the remote identity source itself and does not remove the user account from other identity providers).

Parameters

ParameterDescriptionParameter TypeData Type
user_idThe user IDpathstring
authentication
body{
  "principal": "Object",
  "authenticated": true,
  "credentials": "Object",
  "details": "Object",
  "authorities": [
    "?"
  ]
}

Response Messages

HTTP Status CodeResponse Model
204If the deletion succeeded
401If authentication failed
403If the issuer of the request is not authorized to delete users
404If the user being deleted does not exist
defaultSuccess

GET /users/{user_id}/otp

Returns the two-factor authentication (one-time password) settings for a user. This object contains whether or not OTP two-factor authentication is enabled and links to the URLs used in the enabling workflow.

Two-factor authentication is not enabled until a user has paired the device by validating that it can generate the correct credentials. This is done by using a POST to the seeds URL to generate a seed value, and then configuring Google Authenticator or a compatible application with that seed. Then, a PUT to the pairing URL along with the ID of the generated seed and two tokens will pair the device and enable OTP.

A user must include valid username and password credentials for this request and may only retrieve settings for themselves.

Parameters

ParameterDescriptionParameter TypeData Type
user_idThe ID of the user whose OTP settings are being retrievedpathstring

Response Messages

HTTP Status CodeResponse Model
200If the OTP settings were retrieved
401If the request does not include valid username and password credentials
403If the issuer of the request is not authorized to view users
404If the user does not exist
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "pairing_uri": "string",
  "uri": "string",
  "enabled": true,
  "seeds_uri": "string"
}

GET /users/{user_id}/otp/pairing

Gets a template for updating with the necessary information to make a pairing. The object returned from this API has the properties needed to fill in for the PUT request to the same URL in order to pair with a device and enable two factor authentication.

A user must include valid username and password credentials for this request and may only retrieve settings for themselves.

Parameters

ParameterDescriptionParameter TypeData Type
user_idThe ID of the user who is pairing a devicepathstring

Response Messages

HTTP Status CodeResponse Model
200If the request is successful
401If the request is not authorized with correct username and password credentials for the user being accessed
404If the user does not exist
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "second_token": "string",
  "uri": "string",
  "seed_id": "string",
  "first_token": "string"
}

PUT /users/{user_id}/otp/pairing

Updates two-factor authentication (one-time password) settings to pair a token generating device with the user account. After a GET request is made to the OTP settings for the first time and a seed key is generated, that key should be entered into a supported token-generating application such as Google Authenticator. By updating the OTP
settings with two sequential tokens generated from that device, the OTP device will be enabled and two factor authentication will be active for the user account. 

This API requires authentication with username and password as an additional security requirement. Users may only update OTP settings for themselves.

Parameters

ParameterDescriptionParameter TypeData Type
user_idThe ID of the user whose OTP settings are being updatedpathstring
otpThe OTP settings. This should include the properties "first_token" and "second_token" which are two sequential tokens generated by the token- generating device after it has been seeded with the key.body{
  "second_token": "string",
  "uri": "string",
  "seed_id": "string",
  "first_token": "string"
}

Response Messages

HTTP Status CodeResponse Model
200If the pairing is successful
400If the request does not include two valid tokens
401If the request is not authorized with correct username and password credentials for the user being accessed
404If the user does not exist
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "second_token": "string",
  "uri": "string",
  "seed_id": "string",
  "first_token": "string"
}

DELETE /users/{user_id}/otp/pairing

Disables one-time passwords (two factor authentication) for a user. This will disable two factor authentication for a user which has previously enabled it. The request can be executed by an admin user only.

The request does not do anything if two factor authentication is already disabled.

Parameters

ParameterDescriptionParameter TypeData Type
user_idThe ID of the user whose two factor authentication is being disabledpathstring

Response Messages

HTTP Status CodeResponse Model
200If the two factor authentication was successfully disabled for the user
404If the user does not exist
defaultSuccess

POST /users/{user_id}/otp/seeds

Create a new seed value for the user which can be used to pair a device. A user must include valid username and password credentials for this request and may only retrieve settings for themselves.

Parameters

ParameterDescriptionParameter TypeData Type
user_id

The ID of the user for whom the seed is being generated.

pathstring

Response Messages

HTTP Status CodeResponse Model
200If a seed value is created successfully
401If the request is not authenticated with proper username and password credentials for the user the seed is being generated for
404If the user does not exist
409If OTP two factor authentication pairing has already been completed
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "seed": "string",
  "id": "string"
}

GET /users/{user_id}/password

Returns a password change request template. This API returns a password model, but does not include the current password. The password property will be set to an empty string. The password property may be changed to a new password and sent back via a PUT operation to update a user's password.

Ths API can only update passwords for users in the local identity source. Remote users' passwords must be managed via the remote identity provider.

Parameters

ParameterDescriptionParameter TypeData Type
user_id

The ID of the user whose password will be changed

pathstring
authentication
body{
  "principal": "Object",
  "authenticated": true,
  "credentials": "Object",
  "details": "Object",
  "authorities": [
    "?"
  ]
}

Response Messages

HTTP Status CodeResponse Model
200If the password model was returned
401If authentication failed
403If the issuer of the request is not authorized to change this user's password
404If the user does not exist
405If the user is from a remote identity source
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "password": "string",
  "reset_uri": "string",
  "uri": "string"
}

PUT /users/{user_id}/password

Update a user's password. This API requires HTTP Basic authentication to function. The credentials of the Authorization header must authenticate the issuer of the request as the user whose password is being changed.

Parameters

ParameterDescriptionParameter TypeData Type
user_id

The ID of the user whose password will be changed

pathstring
passwordThe JSON object with the new passwordbody{
  "password": "string",
  "reset_uri": "string",
  "uri": "string"
}
bindingResult
body{
  "suppressedFields": [
    "string"
  ],
  "model": "Map",
  "propertyEditorRegistry": "PropertyEditorRegistry",
  "target": "Object"
}


Response Messages

HTTP Status CodeResponse Model
200If the update was successful
400If the password model is not valid
401If authentication failed or authentication was not HTTP Basic
403If the issuer of the request is not authorized to change this user's password
404If the user does not exist
405If the user is from a remote identity source
defaultSuccess; JSON returned in form of schema shown below

Schema

{
  "password": "string",
  "reset_uri": "string",
  "uri": "string"
}

POST /users/{user_id}/password/resets

Resets a user's password. Resetting a password will send an email to the user with a link they may use to reset the password. The user can browse to that location to use a form to specify the new password. When performing a password reset through the API, the user's current password is also invalidated, preventing authentication until the password is reset.

In order to reset a user's password, that user must have a valid email address specified. If no email address is specified and their username is in the form of an email address, their username will be assumed to be the email address. If a user's username is also not in the form of an email address this request will fail.

Resetting a password via the API is only allowed for administrators.

Parameters

ParameterDescriptionParameter TypeData Type
user_id

The ID of the user whose password will be changed

pathstring

Response Messages

HTTP Status CodeResponse Model
204If the reset was successful
400If the user lacks an email address to which the reset link can be sent
401If no authentication credentials were provided
403If the requesting user is not an administrator
404If the user does not exist
405If the user is from a remote identity source
defaultSuccess