public-api-docs

🔑 Authentication

We use JWTs to authenticate clients when accessing the Wunder Platform.

The response includes a JWT access token, in field accessToken, which is used to authenticate against the Wunder Platform. The response also includes a JWT refresh token, in field refreshToken, which is used to retrieve a new access token after expiration.

The default expiration time for the access token is 5h. This value can be configured for each tenant.

The access token can also be used to explore the API with Stoplight.

Usage

Use the Widget or the API endpoints:

to sign in and use the retrieved accessToken to authenticate. The accessToken needs to be passed as HTTP Authorization Header with Bearer {accessToken} as value for API calls.

In case you want to explore the API with Stoplight you can use the widgets to get a JWT access keys for further API calls.

To use these login widgets:

  1. Login with one of the two widgets below by entering your authentication details
  2. Copy the value of the accessToken field of the response
  3. When using an endpoint paste the content into the Token field and make sure that the correct tenant is configured It should look like this: image.png

Login Widgets

Standard login (email/password)

These login widgets allow login with username and password and retrieve a standard login token.

```production http { “method”: “POST”, “url”: “/{tenant}/auth/sign-in-email”, “baseUrl”: “https://go.api.gourban.services/v1”, “body”: { “email”: “your email”, “password”: “your secret password” } }


### Login with API key

These login widgets allow login as API client with `clientId` and `clientKey`.

```production http
{
  "method": "POST",
  "url": "/{tenant}/auth/sign-in-api-client",
  "baseUrl": "https://go.api.gourban.services/v1",
  "body": {
    "clientId": "your client id",
    "clientKey": "your secret client key"
  }
}

User OTP login - phone number and code

Endusers can also log in with their phone number and a one-time-code (OTP) sent to their phone that they need to enter to log in. This method will also provision a fresh user if the phone number is not yet associated with an existing user.

1. Request an OTP code per phone number

```production http { “method”: “POST”, “url”: “{tenant}/front/customers/create-or-sign-in-with-phone-number”, “baseUrl”: “https://go.api.gourban.services/v1”, “body”: { “phoneNumber”: “your phone number”, “branchId”: “home business unit the user belongs to” } }


see [Create or sign in with phone number](../reference/user-api.yaml/paths/~1customers~1create-or-sign-in-with-phone-number/post) for details.

Depending on your tenant's configuration, it might be necessary to provide a signature to prevent foreign sign-ups, DDoS attacks and replay attacks.
See [Signature](/docs/#signature) for details how to calculate the signature on the client-side.

#### 2. Enter OTP code and authenticate

Retrieve the one-time-code (OTP) sent to your phone number and enter it in the request body.

```production http
{
  "method": "POST",
  "url": "/{tenant}/auth/sign-in-phone-number",
  "baseUrl": "https://go.api.gourban.services/v1",
  "body": {
    "phoneNumber": "your phone number",
    "code": "the OTP code you received"
  }
}

see Sign in with phone number for details.

User OTP login - email code

Endusers can also log in with their email address alone and a one-time-code (OTP) sent to their email address that they need to enter to log in. This method will also provision a fresh user if the email address is not yet associated with an existing user.

1. Request an OTP code per email address

```production http { “method”: “POST”, “url”: “{tenant}/front/customers/create-or-sign-in-with-email-code”, “baseUrl”: “https://go.api.gourban.services/v1”, “body”: { “email”: “your email address”, “branchId”: “home business unit the user belongs to” } }


see [Create or sign in with email code](../reference/user-api.yaml/paths/~1customers~1create-or-sign-in-with-email-code/post) for details

Depending on your tenant's configuration, it might be necessary to provide a signature to prevent foreign sign-ups, DDoS attacks and replay attacks.
See [Signature](/docs/#signature) for details how to calculate the signature on the client-side.

#### 2. Enter OTP code and authenticate

Retrieve the one-time-code (OTP) sent to your email address and enter it in the request body.

```production http
{
  "method": "POST",
  "url": "/{tenant}/auth/sign-in-email-code",
  "baseUrl": "https://go.api.gourban.services/v1",
  "body": {
    "email": "your email address",
    "code": "the OTP code you received"
  }
}

see Sign in with email code for details