Account API

Endpoint Index

Action	Endpoint
Authenticate a standard account	POST /account/authenticate
Authenticate an admin account	POST /account/authenticateAdmin
Authenticate a client or tenant admin account (SSO)	POST /account/sso/authenticateClient
Renew an authentication token	POST /account/renewAuthentication
Unlock an account that has been locked out due to failed login attempts	POST /account/unlock
Update a password	PATCH /account/v1/accounts/password

Authentication

Authenticate a standard account¶

POST /account/authenticate

Request:

Name	Position	Type	Required
body	body	AuthenticateRequest	optional
hostName	query	string	optional
tenantName	query	string	optional

Response: AuthenticateResponse

Note

Use /authenticate for authenticating as a regular user (in which case you must specify a tenantName or hostName), or for an administration account for deploying configurations (in which case you should not specify a tenantName or hostName.)

Authenticate an admin account¶

POST /account/authenticateAdmin

Request:

Name	Position	Type	Required
body	body	AuthenticateRequest	optional
hostName	query	string	optional
tenantLocator	query	string	optional
tenantName	query	string	optional

Response: AuthenticateResponse

Note

Use /authenticateAdmin for authenticating as a “tenant administrator.” It’s the equivalent of logging in as an administrator in the Socotra Administration UI to modify users, maintain external integrations, and query plugin logs. You must specify one of the tenantLocator, hostName, or tenantName. This type of account token cannot be used to deploy configurations.

Note

Values for hostName and tenantName can be included in either the query string or the AuthenticateRequest

Authenticate a client or tenant admin account (SSO)¶

POST /account/sso/authenticateClient

Request:

Name	Position	Type	Required
request	body	SsoClientAuthenticateRequest	required

Response: AuthenticateAdminResponse

Renew an authentication token¶

POST /account/renewAuthentication

Response: AuthenticateResponse

AuthenticateRequest¶

required
password string
username string

optional
hostName string
tenantName string

AuthenticateResponse¶

required
expiresTimestamp timestamp
authorizationToken string

SsoClientAuthenticateRequest¶

required
clientId string
clientSecret string

optional
hostName string

AuthenticateAdminResponse¶

required
expiresTimestamp timestamp
authorizationToken string

Account Lockout Reset

Unlock an account that has been locked out due to failed login attempts¶

POST /account/unlock

Request:

Name	Position	Type	Required
request	body	AccountUnlockRequest	required

Response: void

Note

To unlock any account you must be authenticated as an admin user.

AccountUnlockRequest¶

required
username string

optional
hostName string
tenantName string

Note

To unlock a tenant user account you must specify both the username and hostname in the request. To unlock another admin user you must specify only the username.

Password Change

A user can change their password with the following endpoint:

Update a password¶

PATCH /account/v1/accounts/password

Request:

Name	Position	Type	Required
passwordRequest	body	PasswordChangeRequest	required

Response: void

PasswordChangeRequest¶

required
oldPassword string
password string

optional
logout boolean

The logout property, if set to true, will logout all sessions for the user upon the password change. The default value is false.

Note

Note that the path for the above endpoint is /accounts and not /account.