Postman Guide

This guide describes the OAuth 2.0 Authorization Code Flow with the “DocCheck Access – OAuth2” Postman collection to obtain an access token and call protected user data.

Download Postman Collection

Purpose

• Obtain an authorization code → exchange it for an access token → call the user data endpoint.

Prerequisites

• DocCheck client credentials (client_id, client_secret)
• Registered redirect_uri (must exactly match the URL registered with DocCheck)
• Postman installed

License differences

Basic

• You can fetch an access token (Authorization Code → Token Exchange).
• Passing state or scopes is not allowed.
• Important: scope and state must be disabled in all requests (do not send them), not just left empty.
• Access to the user data endpoint is not included in the Basic license.

Economy & Business

• You can pass and validate the state parameter.
• You can set/request scopes.
• The access token can additionally be used to retrieve user data from the user_data_url endpoint.

Preparation: Set collection variables

Open the collection in Postman and fill in the following values under “Variables”:

• client_id: your client ID
• client_secret: your client secret
• redirect_uri: your registered redirect URL
• scopes: desired scopes (Economy/Business only; do not use in Basic and disable in requests)
• state: random string for CSRF protection (Economy/Business only; do not use in Basic and disable in requests)
• auth_code: leave empty; it will be set after step 1
• auth_url: https://auth.doccheck.com/en/authorize?
• token_url: https://auth.doccheck.com/token
• user_data_url: https://auth.doccheck.com/api/users/data

Basic license

Even if scopes/state variables are empty, Postman may still send empty query parameters. Disable these parameters in the respective request (in the “Params” tab, uncheck the box or remove the row) so that they are not transmitted.

Flow

1. Request authorization code (request “Auth”)

• Open the “Auth” request.
• Review the query parameters. They reference the variables above.
• Basic: Disable/remove the scope and state parameters in the “Params” tab so they are not present in the URL.
• Open the full URL in the browser (in Postman via “Open in browser” or by copying the URL).
• Log in to DocCheck and grant consent.
• After the redirect to your redirect_uri, copy the code parameter from the target URL. For Economy/Business, also verify state.
• Paste the value into the auth_code collection variable.

2. Fetch access token (request “Token”)

• Open “Token” (POST https://auth.doccheck.com/token).
• Body: x-www-form-urlencoded with:
  • client_id =
  • client_secret =
  • grant_type = authorization_code
  • code =
  • redirect_uri =
• Send the request. The expected response includes access_token, token_type, expires_in and possibly refresh_token.

Optional: Automatically store the token as a collection variable in the “Tests” tab of the “Token” request:

pm.collectionVariables.set('access_token', pm.response.json().access_token);

3. Call protected resource (request “Userdata”)

License requirement

This step is available for Economy/Business only. In the Basic license, access to the user data endpoint is not provided.

• Open “Userdata” (GET https://auth.doccheck.com/api/users/data).
• Set authentication:
  • Simple: “Authorization” tab → Type “Bearer Token” → paste the access_token manually from step 2 or use if stored via test.
  • Alternatively via header: Authorization: Bearer <access_token>.
• Send the request. Expected response: 200 OK with user data, depending on scopes and grants.

Scopes

• Applies to Economy/Business. In Basic, scopes are not available and must be disabled (do not send the parameter).
• Choose scopes according to the license model. Empty scopes mean no scopes are requested during login and, consequently, no additional data is available at the user data endpoint. Refer to DocCheck’s documentation for exact scope names.

Optional: Use Postman’s built-in OAuth 2.0 flow

In a request’s “Authorization” tab, select Type “OAuth 2.0” → “Get New Access Token”:

• Auth URL:
• Access Token URL:
• Client ID:
• Client Secret:
• Scope:
• State:
• Redirect URI: your registered redirect_uri
• Enable “Authorize using browser” → log in → “Use Token”.

Note:

• Economy/Business: Fill Scope/State as needed.
• Basic: Leave Scope and State completely empty and ensure they do not appear in the generated authorization URL (no &scope=/&state=). If necessary, verify/remove them in the request’s auth helper before authorizing.