Endpoints

GET /accountchanges

List AccountChange objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of AccountChange

POST /accountchanges

Creates a new AccountChange object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /accountchanges/:id

Fetch a AccountChange object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: AccountChange

PUT /accountchanges/:id

Update an existing AccountChange object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: AccountChange

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /accountchanges/:id

Delete a AccountChange object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /accounts

List Account objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of Account

GET /accounts/:id

Fetch a Account object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: Account

GET /accounts/:id/password

Check if an initial password exists for an account without retrieving it.

POST /accounts/:id/password

Fetch the initial password for the account

GET /activationcodes

List ActivationCode objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of ActivationCode

POST /activationcodes

Creates a new ActivationCode object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /activationcodes/:id

Fetch a ActivationCode object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: ActivationCode

PUT /activationcodes/:id

Update an existing ActivationCode object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: ActivationCode

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /activationcodes/:id

Delete a ActivationCode object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /apikeys

List APIKey objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of APIKey

POST /apikeys

Creates a new APIKey object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Body: The plaintext API secret

GET /apikeys/:id

Fetch a APIKey object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: APIKey

PUT /apikeys/:id

Update an existing APIKey object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: APIKey

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /apikeys/:id

Delete a APIKey object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /apps

List App objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of App

POST /apps

Creates a new App object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /apps/:id

Fetch a App object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: App

PUT /apps/:id

Update an existing App object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: App

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /apps/:id

Delete a App object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

POST /auth

Check if the session is authorized to execute intent.

The server returns an AuthResponse even if the request is unauthorized.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.

Response:

POST /auth/activate

Activate the user

Response:

  • Status 204 : Success
  • Status 403 : An activation code is required but has not been provided

POST /auth/activation_code

Initialize an inactive account.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.
  • Form code - The activate code

Response:

  • Status 204 : Success
  • Status 403 : The access code is invalid

POST /auth/backup

Provide a backup code. Backup codes are single use, so after this call the backup code will no longer be valid.

Request:

  • Form code - The activate code

Response:

  • Status 204 : Success
  • Status 403 : The backup code is invalid

POST /auth/boost

Increase the integrity level of another session.

Request:

  • Body: an IntegrityLevelChangeIntent received from a previously attempted operation.

Response:

  • Status 204 : Success
  • Status 400 : Bad Request, if the request is badly formed, if the intent has expired.
  • Status 401 : Unauthorized, if the current session doesn’t have equal or greater integrity to the target integrity level.
  • Status 403 : Forbidden, if the session belongs to a different user and you are not an administrator, or if the user does not match the user of the other session.
  • Status 409 : Conflict, if the device ID does not match the device ID of the session, or if the other session has failed with an error.

POST /auth/email

Provide the user’s email address.

Request:

  • Form email - The user’s email address

Response:

  • Status 204 : Success
  • Status 400 : When the X-Error-Code response header is Account Missing, then no matching email address is found.

POST /auth/location

Provide a location report.

Request:

  • Form lat - The user’s reported position latitude.
  • Form long - The user’s reported position longitude.

Response:

  • Status 204 : Success

POST /auth/mobile/start

Start the mobile-app authentication flow. Sends an alert to all registered devices.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.

Response:

  • Status 204 : Success
  • Status 400 : No mobile devices were found.

POST /auth/oauth2rp/:appID

Start an OAuth 2.0 reply-party authentication flow. The browser should be redirected to the URL returned.

appID is the ID of an App that supports OAuth 2.0 RP.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.
  • Form next - a BrowserLocation of the user’s intended next state (optional)

Response:

POST /auth/otp/start

Sends an email message to the specified address (or the user’s primary email address if none is specified. The email contains a link, which when clicked, verified that the user has received the email.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.
  • Form email - The email address to use (optional)

Response:

POST /auth/password

Provides a user’s password.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.
  • Form password - The password

Response:

  • Status 204 : Success
  • Status 403 : The password is incorrect.
  • Status 429 : Too many unsuccessful requests have been received. Check the X-Next-Attempt header for the time when a new attempt will be accepted.

POST /auth/pin

Provides a user’s PIN.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.
  • Form code - The PIN

Response:

  • Status 204 : Success
  • Status 403 : The PIN is incorrect.
  • Status 429 : Too many unsuccessful requests have been received. Check the X-Next-Attempt header for the time when a new attempt will be accepted.

DELETE /auth/pstn/:pstnDeviceID

Cancel a PSTN request.

Response:

  • Status 204 : Success

POST /auth/pstn/:pstnDeviceID/finish

Provide a user response to a PSTN challenge.

Request:

  • Form code - The code received via SMS or voice call.

Response:

  • Status 204 : Success
  • Status 403 : The code was not correct.

POST /auth/pstn/:pstnDeviceID/start

Starts a PSTN (public switched telephone network) sign in. Sends an SMS message or places a voice call, as guided by the configuration of the PSTNDevice.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.

Response:

  • Status 204 : Success
  • Status 422 : The selected device has not been verified.

POST /auth/totp

Provide a code from a TOTP app

Request:

  • Form code - The code displayed in the TOTP app

Response:

  • Status 204 : Success
  • Status 403 : The code was not correct.

POST /auth/u2f/finish

Respond to a U2F challenge

Response:

  • Status 200 : Success

POST /auth/u2f/start

Retrieve the challenge information to start a U2F authentication

Response:

  • Status 200 : Success

POST /auth/vouch

Create a new vouch request.

Request:

  • Form intent - The signed intent received from the server in response to a rejected request.

Response:

  • Status 200 : Success

GET /auth/vouch/:id

Fetch information about the state of a vouch request.

Response:

  • Status 200 : Success

DELETE /auth/vouch/:id

Cancel a pending vouch request

Response:

  • Status 200 : Success

POST /auth/vouch/:id/video

Supply the video for a vouch request.

Response:

  • Status 204 : Success

GET /events

Stream events via websocket.

The events endpoint allows allows you to be notified of changes to objects or other events via websockets. Each inbound message is an EventStreamRequest object consisting of a Kind and an optional ID.

The field Kind is an object type name such as “Tenant”, “APIKey”, “App”, “User”, “Group”, “VirtualHost”, “ActivationCode”, or “VouchRequest”.

Each outbound message is a ListItem object. When you’ve subscribed to changes for an object kind, the server will first send all the existing objects. Once the existing objects have been sent, it will send an object with an empty ID. This special marker indicates that the subscription has caught up with existing changes and that any future frames for this kind correspond to new changes. (You might use this to hide a progress indicator, for example).

When an object has been deleted the corresponding frame’s Item property will be empty. Otherwise, changes represent either a new object or an object update.

The special kind Auth tracks the current session’s auth state. The items are AuthResponse objects.

The special kind OtherSession tracks other sessions for the same users. The items are OtherSession objects.

If the underlying user session’s integrity level changes, the server will send a ListItem with the status code 100 (Continue) and the status text of “Integrity Level Changed” and then disconnect the session. On receiving such a message, the client should immediately reconnect.

GET /groups

List Group objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of Group

POST /groups

Creates a new Group object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /groups/:id

Fetch a Group object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: Group

PUT /groups/:id

Update an existing Group object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: Group

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /groups/:id

Delete a Group object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

POST /groups/:id/members/:user

Add a user to a group.

DELETE /groups/:id/members/:user

Remove a user from a group.

POST /groups/:id/members/:user/activate

Activate a user in a group.

POST /groups/:id/members/:user/approve

Approve a user for membership in a group.

POST /groups/:id/members/:user/reject

Reject a user from membership in a group.

POST /groups/:id/members/:user/unreject

Delete the rejection of a user from membership in a group.

POST /groups/:id/members/:user/use

Mark that a user has used their membership in a group.

GET /groups/report.csv

Fetch a list of all approvals for all active group members. The report contains the following columns:

  • group_id - The group ID
  • group_name - The name of the group
  • user_id - The user ID
  • user_email - The user’s primary email address
  • last_used - The time the group membership was last used
  • reason - The reason given for accessing the group
  • approver_user_id - The user ID of the approver
  • approver_email - The primary email address of the approver
  • approved_time - The time access was approved
  • approved_reason - The reason given for approval, if any.

GET /metrics

List Metric objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of Metric

GET /metrics/:id

Fetch a Metric object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: Metric

GET /remoteagents

List RemoteAgent objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of RemoteAgent

GET /remoteagents/:id

Fetch a RemoteAgent object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: RemoteAgent

GET /scriptlogs

List ScriptLog objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of ScriptLog

GET /scriptlogs/:id

Fetch a ScriptLog object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: ScriptLog

GET /scripts

List Script objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of Script

POST /scripts

Creates a new Script object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /scripts/:id

Fetch a Script object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: Script

PUT /scripts/:id

Update an existing Script object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: Script

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /scripts/:id

Delete a Script object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

POST /scripts/test

Run the tests associated with a ScriptLog, and return the results.

Request:

  • Body: an unsaved Script object.

Response:

  • Status 204 : Success
  • Status 500 : Compile Failed
  • Body: lines, each containing a ScriptLog.

GET /tenant

Fetches the global Tenant object.

Response:

  • Header Etag - An opaque string that changes every time the object changes.
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Body: Tenant

PUT /tenant

Status 412: The If-Match header does not contain the current etag.

Stores the global Tenant object.

You must provide an “If-Match” header with the value of the Etag from a previous call to the GET method. If the current Etag does not match the value in If-Match, then the status is 412 Precondition Failed.

Request:

  • Header If-Match - an etag from a previous call to GET.
  • Body: a Tenant object

Response:

  • Status 204 : Successfully stored the object.
  • Status 304 : The object is unchanged.

GET /users

List User objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of User

POST /users

Creates a new User object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /users/:id

Fetch a User object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: User

PUT /users/:id

Update an existing User object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: User

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /users/:id

Delete a User object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

POST /users/:id/merge

Merge the user given by /from/ into the user given by /:id/

Response:

  • Status 204 : Success
  • Status 404 : The object does not exist.

GET /users/:id/reference-video

Fetch the user’s reference video.

Response:

  • Status 200 : Success
  • Status 404 : The reference video does not exist
  • Header Content-Type - video/webm
  • Header X-Magic-Words - a comma separated list of the magic words used when recording the reference video.
  • Body: The webm encoded contents of the user’s reference video.

PUT /users/:id/reference-video

Set or replace a reference video for the user.

Request:

  • Header X-Magic-Words - a comma separated list of the magic words used to record this video.
  • Body: The webm encoded contents of the user’s new reference video.

POST /users/:id/suspend

Suspend the user. When suspended the user cannot log into the console or any apps.

You can specify one or both of after and before to schedule the suspension. If you omit after, then the suspension begins immediately. If you omit before then the suspension lasts indefinitely.

Response:

  • Status 204 : The user was suspended.

POST /users/:id/unsuspend

Unsuspend (resume) the user.

Response:

  • Status 204 : The user was unsuspended.

GET /users/me

Fetch the current user.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: User

GET /users/merge

Fetch a list of suggested user merge operations for all users.

Response:

  • Status 200 : Success
  • Header Content-Type - application/x-json-lines
  • Body: Lines of UserMergeSuggestion

GET /virtualhosts

List VirtualHost objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of VirtualHost

GET /virtualhosts/:id

Fetch a VirtualHost object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: VirtualHost

POST /virtualhosts/:id

Creates a new VirtualHost object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

PUT /virtualhosts/:id

Update an existing VirtualHost object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: VirtualHost

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /virtualhosts/:id

Delete a VirtualHost object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /vouchrequests

List VouchRequest objects.

Filter expressions restrict the view to only matching records. You may specify filter more than once, in which case the items are returned if the match each expression. The form of each expression is field operator value. Operators are <, <=, =, >=, or >. Values must be encoded using JSON. For example to list all the items whose Name is “Alice”, filter would be Name="Alice".

You can implement coherent paging by invoking this endpoint in a loop, setting start to the value given in the X-End-Cursor HTTP trailer from the previous response.

Request:

  • Query limit - The maximum number of items to return.
  • Query offset - Start with the n-th item.
  • Query start - Start with the specified cursor position.
  • Query end - End at the specified cursor position.
  • Query order - Order by the specified field name. May be specified more than once. Prefix the field name with “-” to reverse the order.
  • Query filter - A filter expression. May be specified more than once.

Response:

  • Status 200 : Success
  • Header X-Start-Cursor - The starting cursor position (if limit is specified and < 1000)
  • Header X-End-Cursor - The final cursor position (if limit is specified and < 1000)
  • Header Content-Type - application/x-json-lines
  • Body: Lines of ListItem of VouchRequest

POST /vouchrequests

Creates a new VouchRequest object.

Request:

Response:

  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

GET /vouchrequests/:id

Fetch a VouchRequest object.

Request:

  • Header If-None-Match - return the content only if the Etag is different than the one provided in the request.

Response:

  • Status 200 : Success
  • Status 404 : The object does not exist.
  • Header Etag - An opaque string that changes every time the object changes.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.
  • Header Content-Type - application/json
  • Body: VouchRequest

PUT /vouchrequests/:id

Update an existing VouchRequest object.

If the object has changed since your GET, the request will be rejected with 412 Precondition Failed. If you see this error, you should re-fetch the object, re-apply your changes, and then retry the PUT.

Request:

  • Header Content-Type - application/json
  • Header If-Match - the Etag from a previous GET
  • Body: VouchRequest

Response:

  • Status 204 : The object was updated.
  • Status 304 : The object is unchanged.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.

DELETE /vouchrequests/:id

Delete a VouchRequest object.

You should perform a GET to determine the current version of the object and preserve the corresponding Etag. When you make this request, you must provide the Etag from a previous GET in the If-Match header. If the object’s etag is unchanged since your request, then the operation will succeed. Otherwise, the HTTP status will be 412. You should re-fetch the object with GET, verify that the object should still be deleted in it’s current state, and then retry the delete.

Request:

  • Header If-Match - the Etag from a previous GET

Response:

  • Status 204 : The object was deleted.
  • Status 404 : The object does not exist.
  • Status 412 : The If-Match header does not contain the current etag.
  • Header X-Id - The object ID
  • Header Location - The full URL to the object
  • Header X-Create-Time - The time the object was created.
  • Header Last-Modified - The time that the object was last modified.