How do OAuth clients work in Inxmail?

OAuth clients in Inxmail use OAuth2 with Authorization Code. Here is a simplified diagram of how the various participants interact.

See below for more detailed information on the steps involved.

Steps in the process

  1. The user accesses a resource in the integration that requires access to the Inxmail API.

  2. The integration redirects the user to Inxmail so that they can request initial authorization.

  3. The user authenticates using their Inxmail username and password. They provide the integration with explicit permission to act on their behalf (consent screen).

  4. After successful authentication, the integration stores the refresh token.

  5. Using a valid access token, the integration makes an authenticated call to the Inxmail API.

After this initial authorization, the integration is permitted to act on behalf of the user. The integration can use the (persistent) refresh token to request a (temporary) access token at any time. The access token enables the integration to make authenticated requests to the Inxmail API on behalf of the user.

Detailed Steps in the Process

When accessing an integration application for the first time, the user will need to log in to Inxmail one time and allow the integration to interact with Inxmail on their behalf (consent screen).

Prerequisite: The user must be created in the Users navigation item in Inxmail and have all rights required to use the integration application.

  1. The user accesses a resource in the integration that requires access to the Inxmail API.

  2. The integration redirects the user to Inxmail so that they can request initial authorization.

  3. The user authenticates using his or her Inxmail credentials and allows the integration to act on their behalf (consent screen).

    Background: The integration acts on behalf of the user. It can do everything the user can do. If you want to restrict the rights of an integration, we recommend that you use a special integration user.

    The integration initiates the Authorization Code Grant to authorize the integration to act on behalf of the Inxmail user.

  4. After successful authentication, the integration receives a refresh token and an access token from Inxmail. The integration can use the (persistent) refresh token to request (temporary) access tokens from Inxmail at a future time.

    Protect your refresh token: Since it is possible to request new access tokens using a refresh token without further user interaction, you will need to store the refresh token at a secure location just like you would your password.

  5. Using a (temporary) access token, the integration calls the Inxmail API. Inxmail enables access to the requested Inxmail resource.

When the integration application is called at a later time, the process is simplified, i.e., the integration already has a (persistent) refresh token. The request for the (temporary) access token takes place in the background. As a result, the programs appear seamlessly integrated from a user perspective (Inxmail users do not need to log in again).

  1. The user accesses a resource in the integration that requires access to the Inxmail API.

  2. The integration can use the (persistent) refresh token to request a (temporary) access token from Inxmail.

  3. (Step 3 no longer required.)

  4. (Step 4 no longer required.)

  5. The integration uses the access token to call the Inxmail API.

    The call via the access token is done using a URL fragment, for example, https://<space>.my-api.inxmail.de/<resource>.

    Your Refresh Token expires after 30 days of inactivity: If the refresh token is not used for 30 days, you will need to request a new refresh token via the authorization code grant. An integration should assume that a refresh token for a user may no longer be valid.

    Your access token expires after five minutes: Since the access token has a defined life span of five minutes, the integration has to ensure that the access token is valid for the duration of use. Once an access token has expired, the integration must repeat the API request using a newly requested access token. This functionality is provided by default by many OAuth libraries.

Further Information