Skip to content


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:

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: 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.


# > 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": "",
        "prospect": {
            "first_name": "Foo",
            "last_name": "Bar"


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.

Digging deeper

It's strongly recommended to use an OAuth2.0 libray to implement the authentication and authorization process, recommended libraries can be found here.

If you want to read more about what the 'Authorization Code Grant' is, we recommend this documentation.

Getting started

To get started send a mail to: 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.


  User->>External: Integrate WeGroup
  External->> Call authorization endpoint>> Redirect to login challenge
  loop>> Verify Credentials
  end>> Redirect to consent challenge
  loop>> Verify Consent
  end>> Return token
  loop>> Verify grants
  end>>External: Return authorization token
  External->> Call token endpoint>>External: Return access token
  External->> Call API
  External->>User: Show API result
  External->> Call userinfo endpoint>>External: userinfo result

OpenID servers

Discover the OpenID endpoints and obtain information needed to interact with it, including its OAuth 2.0 endpoint locations when clicking on the host.

Environment Host


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

curl -X GET \
    "" \
    -H "Authorization: bearer $BEARER_TOKEN" \
    -H "Content-Type: application/json"


    "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": "",
    "username": "user_1"
    "language": "EN",
    "country": "EN",
    "locale": "en-US",
    "role": "broker",
    "last_login": "1970-01-01T00:00:00.000000",

Lifetime of tokens

Environment Access Token Refresh Token
PRODUCTION 24h infinity


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": "",
        "prospect": {
            "first_name": "Foo",
            "last_name": "Bar"


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).

Scope Description Available in authentication method
api Full API access (this includes all read/write/update/delete API's). SSO
offline Make use of refresh tokens. if no offline scope is asked for no refresh token is returned. SSO
openid Get an OpenID token, this makes it possible to use /userinfo call. SSO
leads:write Be able to push leads to a distribution. SSO / API Token
leads:read Be able to read lead by id. SSO / API Token
parties:update Be able to update a prospect and the risk_objects linked to it. SSO / API Token
parties:read Be able to read a party by id. SSO / API Token
vehicle:read Be able to use the Vehicle Database API. SSO / API Token
address:read Be able to use the Address Database API. SSO / API Token
enterprise:read Be able to use the Company Database API. SSO / API Token