Skip to main content

Authentication

Genesys uses OpenID Connect (OIDC), a simple identity layer on top of the OAuth 2.0 protocol to authenticate users and systems.

You can authenticate as a user or as a service to obtain the access token to interact with the API. A valid access token does not immediately grant you permission to all endpoints. There are security checks in place.

JWT tokens

Tokens are in JWT format and you can check the contents of any JWT token with https://jwt.io

OAuth clients​

There is a big difference between the user of your application and the application itself. When a user (usually a person) interacts with your application (a service) then all actions in Genesys will be executed on behalf of the user. The application itself can also execute actions in Genesys as a service.

For example, an application that reads data from Genesys and checks for spelling errors will authenticate with Genesys as a service. If a person then logs into this application to fix the spelling errors, they authenticate as a user.

In both cases, the application is registered as an OAuth client in Genesys, and will have its own client_id and possibly a client_secret.

Registering a new client​

See Admin > OAuth clients in Genesys Web interface.

OIDC endpoints​

A number of endpoints are involved in OIDC authentication and they are listed at https://api.genesys-pgr.org/.well-known/openid-configuration. Most OIDC libraries will automatically access this URL and use it for auto-configuration.

Authenticating as a service​

This is called client authentication and it is possible to obtain tokens with a simple call to /oauth2/authenticate endpoint.

tip

The best approach is to add an existing OIDC library to your application and let it handle the authentication flow, providing your application only with the final access and, optionally, refresh tokens.

Authenticating a user​

Authenticating a user is a much more engaged process. OIDC requires that the username and password are not provided to the service (i.e. using a login form), and must only be provided to the authentication server.

warning

The best approach is to use an existing OIDC library and let it handle the user authentication flow, providing your application only with the final access and, optionally, refresh tokens.

Example with Postman​

In Postman, under the Authorization tab, select Auth Type: OAuth 2.0 and configure a new token:

  • Token Name: Enter a name for your token to identify it easily for future use in Postman.
  • Grant Type: Select Authorization Code.
  • Callback URL: This URL should match the Registered redirect URI defined for your OAuth2 client in Genesys
  • Auth URL: https://api.genesys-pgr.org/oauth/authorize
  • Access Token URL: https://api.genesys-pgr.org/oauth/token
  • Client ID: Your Client ID.
  • Client Secret: The secret associated with this Client.
  • Scope: Space-separated access scopes, or leave blank.
  • Client Authentication: Use Send as Basic Auth Header.
  • Finally, click the Get New Access Token button and login to Genesys with your user credentials to get the token!