Authentication

To access the WeGroup API, you need to authenticate using one of two methods:

• API token: Limited endpoints available to interact.
• Single sign-on (SSO): Harder to implement but more API endpoints available.

API token

This is the simplest form to make use of the API, but is also very limited in terms of endpoints that are available.

The following actions can be done with an API token:

• Creating a lead
• Make use of our car database
• Make use of our address database
• Make use of our company database

Getting started

Each use case is different, we love to hear how you want to interact with our API, therefor to get started send a mail to: it@wegroup.be to state your use case. This way we will create an API token forged to your needs. This is free of charge.

Each api token has a limited set of scopes depending on your needs.

Usage

# > Pushing a lead

curl -X POST \
    "https://$HOST/v1/api/distributions/$DISTRIBUTION_ID/leads/customers" \
    -H "Authorization: apikey $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "origin": "CRM",
        "backref": "https://wegroup.be",
        "prospect": {
            "first_name": "Foo",
            "last_name": "Bar"
        }
    }'

SSO

As a Partner you can make use of our SSO implementation, this offers partners a seamless way to integrate WeGroup in their application.

When you want to interact with our API on behalf of a WeGroup account, via this way you can use any API a WeGroup customer account can access.

WeGroup uses OAuth 2.0 and OpenID Connect (OIDC) for authorization/authentication.

More specifically, the Authorization Code Grant with PKCE flow is used to obtain an access token, which can be used to make calls to the WeGroup API.

Getting started

To get started send a mail to: it@wegroup.be to state your use case and provide a redirect_url. A client_id and client_secret will be provided so you can start interacting with our API. This is free of charge.

Diagram

sequenceDiagram
  autonumber
  User->>External: Integrate WeGroup
  External->>sso.wegroup.be: Call authorization endpoint
  sso.wegroup.be->>auth.wegroup.be: Redirect to login challenge
  loop
      auth.wegroup.be->>auth.wegroup.be: Verify Credentials
  end
  sso.wegroup.be->>auth.wegroup.be: Redirect to consent challenge
  loop
      auth.wegroup.be->>auth.wegroup.be: Verify Consent
  end
  auth.wegroup.be->>sso.wegroup.be: Return token
  loop
      sso.wegroup.be->>sso.wegroup.be: Verify grants
  end
  sso.wegroup.be->>External: Return authorization token
  External->>sso.wegroup.be: Call token endpoint
  sso.wegroup.be->>External: Return access token
  External->>api.wegroup.be: Call API
  External->>User: Show API result
  External->>sso.wegroup.be: Call userinfo endpoint
  sso.wegroup.be->>External: userinfo result

OpenID servers

Userinfo

When requiring end-user information one may use the /userinfo endpoint.

curl -X GET \
    "https://sso.wegroup.be/userinfo" \
    -H "Authorization: bearer $BEARER_TOKEN" \
    -H "Content-Type: application/json"

Response:

{
    "sub": "e737c7dc-cb7e-45ea-995f-f2c61a23481e",
    "uid": "e737c7dc-cb7e-45ea-995f-f2c61a23481e",  # user id
    "bid": "0c9edeaa-8b3e-4187-a3cd-8feea1620754",  # broker id
    "did": "42f9b29d-a302-44dd-a984-515faacf2acd",  # distribution id
    "email": "user@wegroup.be",
    "username": "user_1"
    "language": "EN",
    "country": "EN",
    "locale": "en-US",
    "role": "broker",
    "last_login": "1970-01-01T00:00:00.000000",
}

Lifetime of tokens

Usage

When executing an SSO flow, you will receive an access_token, this token is a bearer token and is used as follows:

# > Pushing a lead

curl -X POST \
    "https://$HOST/v1/api/distributions/$DISTRIBUTION_ID/leads/customers" \
    -H "Authorization: bearer $BEARER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "origin": "CRM",
        "backref": "https://wegroup.be",
        "prospect": {
            "first_name": "Foo",
            "last_name": "Bar"
        }
    }'

Scopes

A scope is either given (API tokens are bound to a static set of scopes) or asked (via SSO flow you ask for scopes and consent is required).

Example of consent