Authentication API

From Genesys Documentation
Jump to: navigation, search
This topic is part of the manual Genesys Multicloud CX Web-based API Reference for version Current of Developer.



Base path: /auth/v3

POST
/change-password
Change password
Change the user's password.
Parameters
Name Default Description Parameter Type Data Type Required
Authorization bearer The OAuth 2 bearer access token you received from /auth/v3/oauth/token. For example: Authorization: bearer a4b5da75-a584-4053-9227-0f0ab23ff06e header string
request Request body true 
{
  "data": {
    "newPassword": "string",
    "oldPassword": "string",
    "userName": "string"
  },
  "operationId": "string"
}
ChangePasswordOperation
newPassword (string, required):
oldPassword (string, required):
userName (string, optional):
ApiRequestOfChangePasswordOperation
data (ChangePasswordOperation, required):
operationId (string, optional): Used for asynchronous operations to map request and response
Responses
Code Reason
200 Ok 
{
  "data": {
  },
  "errors": [
    {
      "status": {
        "code": 0,
        "detail": {
        },
        "message": "string"
      }
    }
  ],
  "path": "string",
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
ErrorResponse
data (object):
errors (array:ErrorResponse):
path (string):
status (ResponseStatus):
403 Unable to update password
503 Service unavailable
Usage
curl -X POST
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"
-d '{
  "data": {
    "newPassword": "string",
    "oldPassword": "string",
    "userName": "string"
  },
  "operationId": "string"
}'
"https://api-demo.com/auth/v3/change-password?"
GET
/jwt-userinfo
Get user information by access token. The information will be encoded as jwt and returned in 'X-GWS-User' header
Get information about a user by their OAuth 2 access token.
Parameters
Name Default Description Parameter Type Data Type Required
Authorization The OAuth 2 bearer access token. For example: Authorization: bearer a4b5da75-a584-4053-9227-0f0ab23ff06e header string true
Responses
Code Reason
200 Ok 
{
  "data": {
  },
  "errors": [
    {
      "status": {
        "code": 0,
        "detail": {
        },
        "message": "string"
      }
    }
  ],
  "path": "string",
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
ApiResponse
data (object):
errors (array:ErrorResponse):
path (string):
status (ResponseStatus):
Usage
curl -X GET
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/jwt-userinfo?"
GET
/oauth/authorize
Perform authorization
Perform authorization for the Authorization Code Grant type, which is currently the only type supported by the Authentication API. For more information, see Authorization Endpoint. Note: For the optional scope parameter, the API supports only the * value.
Parameters
Name Default Description Parameter Type Data Type Required
Authorization Basic authorization. For example: Authorization: Basic Y3…MQ== header string
client_id The ID of the application or service that is registered as the client. You'll need to get this value from your Engage Cloud representative. query string true
hideTenant false Hide the tenant field in the UI for Authorization Code Grant. query boolean
redirect_uri The URI that you want users to be redirected to after entering valid credentials during an Implicit or Authorization Code grant. The Authentication API includes this as part of the URI it returns in the 'Location' header. query string true
response_type The response type to let the Authentication API know which grant flow you're using. Possible values are code for Authorization Code Grant or token for Implicit Grant. For more information about this parameter, see Response Type. query string true
scope The scope of the access request. The Authentication API supports only the * value. query string
Responses
Code Reason
302 Found 
"string"
401 Unauthorized
Usage
curl -X GET
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/oauth/authorize?client_id=string&hideTenant=true&redirect_uri=string&response_type=string&scope=string"
POST
/oauth/token
Retrieve access token
Retrieve an access token for the Authorization Code Grant type, which is which is currently the only type supported by the Authentication API. For more information, see Token Endpoint. Note: For the optional scope parameter, the API supports only the * value.
Parameters
Name Default Description Parameter Type Data Type Required
Accept The media type the Authentication API should should use for the response. For example: Accept: application/x-www-form-urlencoded header string
Authorization Basic authorization. For example: Authorization: Basic Y3…MQ== header string
client_id The ID of the application or service that is registered as the client. You'll need to get this value from your Engage Cloud representative. formData string
code Authorization code, see Access Token Request for details. formData string
grant_type The grant type you use to implement authentication. formData string true
password The agent's password. formData string
refresh_token See Refresh Token for details. formData string
scope The scope of the access request. The Authentication API supports only the * value. formData string
username The agent's username. formData string
Responses
Code Reason
200 Ok 
{
  "access_token": "string",
  "expires_in": 0,
  "refresh_token": "string",
  "scope": "string",
  "token_type": "string"
}
DefaultOAuth2AccessToken
access_token (string):

The access token.

expires_in (integer):

The time, in seconds, before the token expiration.

refresh_token (string):

The refresh token.

scope (string):

The scope of the token.

token_type (string):

The type of access token — always 'bearer'.

400 Error as specified by standard (username/password is wrong, for example) 
{
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
401 Unauthorized 
{
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
403 Forbidden 
{
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
503 Service unavailable
Usage
curl -X POST
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/oauth/token?"
GET
/openid/userinfo
Get OpenID user information by access token
Get information about a user by their OAuth 2 access token.
Parameters
Name Default Description Parameter Type Data Type Required
Authorization The OAuth 2 bearer access token you received from /auth/v3/oauth/token. For example: Authorization: bearer a4b5da75-a584-4053-9227-0f0ab23ff06e header string true
Responses
Code Reason
200 Ok 
{
  "aud": "string",
  "authorities": [
    {
      "name": "string",
      "privileges": [

      ]
    }
  ],
  "contact_center_id": "string",
  "dbid": 0,
  "email": "string",
  "environment_id": "string",
  "family_name": "string",
  "given_name": "string",
  "properties": {
    "<key>": ""
  },
  "sub": "string",
  "user_name": "string"
}
UserRole
name (string):
privileges (array:string):
OpenIdUserInfo
aud (string):

OpenID Connect 'aud' claim. This is present if user authenticated with openid scope.

authorities (array:UserRole):

Authorities assigned to the user.

contact_center_id (string):

OpenID Connect 'aud' claim. This is present if user authenticated with openid scope.

dbid (integer):

The DBID of the corresponding user record in Configuration Server. This is present if the user belongs to a contact center.

email (string):

OpenID Connect 'email' claim. This is present if user authenticated with openid scope.

environment_id (string):

OpenID Connect 'environment_id' claim. This is present if user authenticated with openid scope.

family_name (string):

OpenID Connect 'family_name' (last name) claim. This is present if user authenticated with openid scope.

given_name (string):

OpenID Connect 'given_name' (first name) claim. This is present if user authenticated with openid scope.

properties (object):

The user's properties

sub (string):

OpenID Connect 'sub' claim. This is present if user authenticated with openid scope.

user_name (string):

OpenID Connect 'aud' claim. This is present if user authenticated with openid scope.

401 Unauthorized
503 Service unavailable
Usage
curl -X GET
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/openid/userinfo?"
GET
/ping
Check connection
Return 200 if user is authenticated otherwise 403.
Responses
Code Reason
200 Ok 
{
  "data": {
  },
  "errors": [
    {
      "status": {
        "code": 0,
        "detail": {
        },
        "message": "string"
      }
    }
  ],
  "path": "string",
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
ApiResponse
data (object):
errors (array:ErrorResponse):
path (string):
status (ResponseStatus):
403 Prohibited
503 Service unavailable
Usage
curl -X GET
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/ping?"
GET
/sign-out
Sign-out a logged in user
Sign-out the current user and invalidate either the current token or all tokens associated with the user.
Parameters
Name Default Description Parameter Type Data Type Required
Authorization The OAuth 2 bearer access token you received from /auth/v3/oauth/token. For example: Authorization: bearer a4b5da75-a584-4053-9227-0f0ab23ff06e header string true
global Specifies whether to invalidate all tokens for the current user (true) or only the current token (false). query boolean
redirectUri Specifies the URI where the browser is redirected after sign-out is successful. query string
Responses
Code Reason
200 Ok 
{
  "data": {
  },
  "errors": [
    {
      "status": {
        "code": 0,
        "detail": {
        },
        "message": "string"
      }
    }
  ],
  "path": "string",
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
ApiResponse
data (object):
errors (array:ErrorResponse):
path (string):
status (ResponseStatus):
401 Unauthorized
503 Service unavailable
Usage
curl -X GET
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/sign-out?global=true&redirectUri=string"
POST
/sign-out
Sign-out a logged in user
Sign-out the current user and invalidate either the current token or all tokens associated with the user.
Parameters
Name Default Description Parameter Type Data Type Required
Authorization The OAuth 2 bearer access token you received from /auth/v3/oauth/token. For example: Authorization: bearer a4b5da75-a584-4053-9227-0f0ab23ff06e header string true
global Specifies whether to invalidate all tokens for the current user (true) or only the current token (false). query boolean
Responses
Code Reason
200 Ok 
{
  "data": {
  },
  "errors": [
    {
      "status": {
        "code": 0,
        "detail": {
        },
        "message": "string"
      }
    }
  ],
  "path": "string",
  "status": {
    "code": 0,
    "detail": {
    },
    "message": "string"
  }
}
ResponseStatus
code (integer):
detail (object):
message (string):
ErrorResponse
status (ResponseStatus):
ApiResponse
data (object):
errors (array:ErrorResponse):
path (string):
status (ResponseStatus):
401 Unauthorized
503 Service unavailable
Usage
curl -X POST
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/sign-out?global=true"
GET
/userinfo
Get user information by access token
Get information about a user by their OAuth 2 access token.
Parameters
Name Default Description Parameter Type Data Type Required
Authorization The OAuth 2 bearer access token. For example: Authorization: bearer a4b5da75-a584-4053-9227-0f0ab23ff06e header string true
Responses
Code Reason
200 Ok 
{
  "authorities": [
    {
      "name": "string",
      "privileges": [

      ]
    }
  ],
  "cmeUserName": "string",
  "contactCenterId": "string",
  "dbid": 0,
  "environmentId": "string",
  "loginName": "string",
  "properties": {
    "<key>": ""
  },
  "username": "string"
}
UserRole
name (string):
privileges (array:string):
CloudUserDetails
authorities (array:UserRole):

Authorities assigned to the user.

cmeUserName (string):

The username in Configuration Server. This property is not set for users who aren't in Configuration Server (for example, applications/services, cloud system admin and so on.)

contactCenterId (string):

The ID of the contact center the user belongs to (if any).

dbid (integer):

The DBID of the corresponding user record in Configuration Server. This is present if the user belongs to a contact center.

environmentId (string):

The ID of the Genesys environment the user belongs to (if any).

loginName (string):

The username in Configuration Server. This property is not set for users who aren't in Configuration Server (for example, applications/services, cloud system admin and so on.)

properties (object):

The user's properties

username (string):

The system-wide unique name of the user. For contact center users, this includes the userName in Configuration Server, the DBID in Configuration Server and the contact center ID. For non-Configuration Server users the username can have other formats.

401 Unauthorized
503 Service unavailable
Usage
curl -X GET
-H "x-api-key: your_API_key"
-H "Content-Type: application/json"

"https://api-demo.com/auth/v3/userinfo?"
Retrieved from "https://all.docs.genesys.com/PEC-Developer/Current/WebAPIs/Authentication (2024-11-03 07:54:04)"
Comments or questions about this documentation? Contact us for support!