HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

Authentication

Welcome Open API uses OAuth 2.0 as it's authorization mechanism. In order to consume the API you need to register an OAuth 2.0 app for a Welcome organization.

The supported OAuth 2.0 flow is authorization code. In this flow the OAuth 2.0 app needs to be a web app hosted in a server. The server hosting the web app must know and protect the client id and client secret.

Authorization server

  1. Host: https://accounts.welcomesoftware.com
  2. Authorization endpoint: <https://accounts.welcomesoftware.com/o/oauth2/v1/auth>
  3. Scopes: openid, profile and offline_access
    (These scopes are delimited by a single space. All of these scopes must be passed to the authorization endpoint)
  4. Token endpoint: https://accounts.welcomesoftware.com/o/oauth2/v1/token
  5. Userinfo endpoint (can be used to validate access token): <https://accounts.welcomesoftware.com/o/oauth2/v1/userinfo>

Registering OAuth 2.0 apps in Welcome

To register an app, you will need to provide the following information

  • Welcome Organization name: Name of a Welcome Organization for which the app will be registered
  • Redirect URL: A valid URL of the server hosting the web app where the Welcome authorization server will send back the authorization code
  • App name: A name for the app

On successful registration, you will receive a client_id and a client_secret from Welcome with which you can request for access_token and refresh_token from the Welcome authorization server.

Authorization code flow

Welcome supports only the authorization code flow for OAuth 2.0.

  1. User opens the web app in browser. User must be registered with the organization with which the app is associated.

  2. User performs some action in the web app to begin the authorization process. In usual case it is clicking a button.

  3. User is redirected to the authorization server.

    HTTP GET
    https://accounts.welcomesoftware.com/o/oauth2/v1/auth?client_id=12345678-1234-1234-1234-123456789012&redirect_uri=https://my-web-app.com/o/oauth/callback&response_type=code&scope=openid%20profile%20offline_access
    

    client_id is the client id of the app that you have registered, and redirect_uri is the redirect url of the app provided when the app was registered.

  4. Authorization server logs the user in, if user is not logged in.

  5. Through logging in, user gives the consent to the app to access the user's data from Welcome.

  6. User is redirected to the redirect url of the app with the authorization code.

    HTTP GET
    https://my-web-app.com/o/oauth/callback?code=87654321-4321-4321-4321-210987654321
    

    code is the authorization code.

  7. The web app makes an HTTP POST request to the authorization server to obtain an access_token and a refresh_token.

    HTTP POST
    https://accounts.welcomesoftware.com/o/oauth2/v1/token
    
    Request payload:
        {
            "client_id": "12345678-1234-1234-1234-123456789012",
            "client_secret": "my-encrypted-secret-1234",
            "code": "87654321-4321-4321-4321-210987654321",
            "grant_type": "authorization_code",
            "redirect_uri": "https://my-web-app.com/o/oauth/callback"
        }
    
    Response payload:
        {
            "access_token": "b3717c0a-6857-4858-8274-9fe7b51180c9",
            "refresh_token": "ff7d31df-ad4d-4a62-9291-877df0757478",
            "id_token": "some-jwt-token",
            "expires_in": 3599,
            "token_type": "Bearer"
        }
    
  8. (Optional) Server can validate the received access token by making an HTTP GET request to the authorization server by passing the access_token in the Authorization HTTP header with Bearer prefix. For example.

    HTTP GET
    https://accounts.welcomesoftware.com/o/oauth2/v1/userinfo
    
    Headers:
      Authorization: Bearer b3717c0a-6857-4858-8274-9fe7b51180c9
    
  9. Now the web server can use the Open API by passing the access_token in the Authorization HTTP header with Bearer prefix. For example.

    HTTP GET
    https://api.welcomesoftware.com/v3/assets
    
    Headers:
      Authorization: Bearer b3717c0a-6857-4858-8274-9fe7b51180c9
      
    
  10. If the access_token expires, the web server can get a new access_token, using the refresh_token, by making an HTTP POST request to the authorization server.

    HT
    TP POST
    https://accounts.welcomesoftware.com/o/oauth2/v1/token
    
    Request payload:
        {
            "client_id": "12345678-1234-1234-1234-123456789012",
            "client_secret": "my-encrypted-secret-1234",
            "refresh_token": "ff7d31df-ad4d-4a62-9291-877df0757478",
            "grant_type": "refresh_token"
        }
    
    Response payload:
        {
            "access_token": "bd680785-b090-40ca-9a32-22df51e96e7a",
            "refresh_token": "e053d83e-14e1-4ba4-b18e-ea654b39a02e",
            "id_token": "some-jwt-token",
            "expires_in": 3599,
            "token_type": "Bearer"
        }
    

Token revocation

You can revoke the tokens generated by the Authorization code flow.

Revoke access token

Revoke an access_token by making an HTTP POST request to the authorization server.

HTTP POST
https://accounts.welcomesoftware.com/o/oauth2/v1/revoke

Request payload:
    {
      "token": "bd680785-b090-40ca-9a32-22df51e96e7a",
      "token_type_hint": "access_token",
      "client_id": "12345678-1234-1234-1234-123456789012",
      "client_secret": "my-encrypted-secret-1234"
    }

Response payload:
    {
        "msg": "success"
    }

Revoke refresh token

Revoke a refresh_token by making an HTTP POST request to the authorization server.

HTTP POST
https://accounts.welcomesoftware.com/o/oauth2/v1/revoke

Request payload:
    {
      "token": "e053d83e-14e1-4ba4-b18e-ea654b39a02e",
      "token_type_hint": "refresh_token",
      "client_id": "12345678-1234-1234-1234-123456789012",
      "client_secret": "my-encrypted-secret-1234"
    }

Response payload:
    {
        "msg": "success"
    }

Revoke token without mentioning any token type

A token can be revoked without passing the token_hint_type field in the request payload. The passed token can either be an access_token or a refresh_token. The authorization server will automatically deduce the type of the token and revoke it.

HTTP POST
https://accounts.welcomesoftware.com/o/oauth2/v1/revoke

Request payload:
    {
      "token": "e053d83e-14e1-4ba4-b18e-ea654b39a02e",
      "client_id": "12345678-1234-1234-1234-123456789012",
      "client_secret": "my-encrypted-secret-1234"
    }

Response payload:
    {
        "msg": "success"
    }

Organization association

An app must be associated with a Welcome organization. An app cannot be associated with multiple Welcome organizations.

Resource Owner

The resource owner authorizing the app, i.e. the Welcome user whose data will be accessed via the Open API, must be registered with the associated organization.

App modes

Apps can be created in development or in production mode depending on your need. If you plan to develop a new app and not publish it to real users, you can leverage the development mode for longer TTL.

Development mode

TTL for access token: 30 days

Production mode

TTL for access token: 1 hour


Did this page help you?