> For the complete documentation index, see [llms.txt](https://docs.vcheckglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vcheckglobal.com/api-reference/authentication.md). # Authentication Authenticate with client credentials to obtain a bearer token for all API requests. ### Which scope to request Scopes follow one rule across every service - the HTTP method decides which one you need. Request the scope once when you issue the token; it applies to every call made with that token. | HTTP method | Scope required | | ---------------------------------------- | ----------------------------------- | | `GET` (read only) | `api-platform/-read` | | `POST`, `PATCH`, `PUT`, `DELETE` (write) | `api-platform/-read-write` | Replace `` with the product you are calling - `monitoring` or `backgroundcheck`. | Service | Read scope | Read and write scope | | ---------------- | ----------------------------------- | ----------------------------------------- | | Monitoring | `api-platform/monitoring-read` | `api-platform/monitoring-read-write` | | Background Check | `api-platform/backgroundcheck-read` | `api-platform/backgroundcheck-read-write` | **Notes** * `-read-write` is a superset of `-read`: a read-write token can also perform every `GET`. Request a single `-read-write` scope if your integration both reads and writes. * Scopes are space-separated, so one token can cover several services, for example `api-platform/monitoring-read-write api-platform/backgroundcheck-read`. * Calling an endpoint without the matching scope returns `403 Forbidden`. * Individual endpoints do not list scopes separately - the rule above is the whole contract. ## Issue Bearer Token > All API requests require a Bearer token in the Authorization header.\ > Tokens expire after 3,600 seconds - cache and reuse the token,\ > request a new one only when it is close to expiry.\ > \ > \*\*Authentication:\*\* None - this endpoint IS the authentication step.\ > \ > \*\*Content-Type:\*\* \`application/x-www-form-urlencoded\`\ > \ > \*\*Get a Token\*\*\ > \ > \| Property | Value |\ > \|---|---|\ > \| URL | \`POST |\ > \| Content-Type | \`application/x-www-form-urlencoded\` |\ > \ > \*\*Request Parameters (form-encoded)\*\*\ > \ > \| Parameter | Type | Required | Description |\ > \|---|---|---|---|\ > \| \`grant\_type\` | string | Yes | Must be \`client\_credentials\` |\ > \| \`client\_id\` | string | Yes | Public identifier issued during onboarding |\ > \| \`client\_secret\` | string | Yes | Private credential issued during onboarding. Store in a vault |\ > \| \`scope\` | string | Yes | Space-separated list of permissions. e.g. \`api-platform/monitoring-read-write\` |\ > \ > \*\*Available Scopes\*\*\ > \ > \| Scope | Access |\ > \|---|---|\ > \| \`api-platform/monitoring-read\` | Read-only access to monitoring endpoints |\ > \| \`api-platform/monitoring-read-write\` | Read and write access to monitoring endpoints |\ > \| \`api-platform/backgroundcheck-read\` | Read-only access to background check endpoints |\ > \| \`api-platform/backgroundcheck-read-write\` | Read and write access to background check endpoints |\ > \ > \*\*Using the Token\*\*\ > \ > Include in all subsequent requests as \`Authorization: Bearer \\`.\ > \ > Tokens expire after \*\*3,600 seconds\*\* - cache and reuse, request a new one only when close to expiry.
```json {"openapi":"3.1.0","info":{"title":"Vcheck Global API","version":"5.4.0"},"tags":[{"name":"Authentication","description":"Authenticate with client credentials to obtain a bearer token for all API requests.\n\n## Which scope to request\n\nScopes follow one rule across every service - the HTTP method decides which one you need.\nRequest the scope once when you issue the token; it applies to every call made with that token.\n\n| HTTP method | Scope required |\n|---|---|\n| `GET` (read only) | `api-platform/-read` |\n| `POST`, `PATCH`, `PUT`, `DELETE` (write) | `api-platform/-read-write` |\n\nReplace `` with the product you are calling - `monitoring` or `backgroundcheck`.\n\n| Service | Read scope | Read and write scope |\n|---|---|---|\n| Monitoring | `api-platform/monitoring-read` | `api-platform/monitoring-read-write` |\n| Background Check | `api-platform/backgroundcheck-read` | `api-platform/backgroundcheck-read-write` |\n\n**Notes**\n\n- `-read-write` is a superset of `-read`: a read-write token can also perform every `GET`.\n Request a single `-read-write` scope if your integration both reads and writes.\n- Scopes are space-separated, so one token can cover several services, for example\n `api-platform/monitoring-read-write api-platform/backgroundcheck-read`.\n- Calling an endpoint without the matching scope returns `403 Forbidden`.\n- Individual endpoints do not list scopes separately - the rule above is the whole contract.\n"}],"servers":[{"url":"https://api-platform.vcheckglobal.net/v2","description":"Vcheck platform (sandbox host issued first; production host after sign-off)"}],"security":[],"paths":{"/oauth2/token":{"post":{"tags":["Authentication"],"operationId":"issueBearerToken","summary":"Issue Bearer Token","description":"All API requests require a Bearer token in the Authorization header.\nTokens expire after 3,600 seconds - cache and reuse the token,\nrequest a new one only when it is close to expiry.\n\n**Authentication:** None - this endpoint IS the authentication step.\n\n**Content-Type:** `application/x-www-form-urlencoded`\n\n**Get a Token**\n\n| Property | Value |\n|---|---|\n| URL | `POST https://api-platform.vcheckglobal.net/v2/oauth2/token` |\n| Content-Type | `application/x-www-form-urlencoded` |\n\n**Request Parameters (form-encoded)**\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `grant_type` | string | Yes | Must be `client_credentials` |\n| `client_id` | string | Yes | Public identifier issued during onboarding |\n| `client_secret` | string | Yes | Private credential issued during onboarding. Store in a vault |\n| `scope` | string | Yes | Space-separated list of permissions. e.g. `api-platform/monitoring-read-write` |\n\n**Available Scopes**\n\n| Scope | Access |\n|---|---|\n| `api-platform/monitoring-read` | Read-only access to monitoring endpoints |\n| `api-platform/monitoring-read-write` | Read and write access to monitoring endpoints |\n| `api-platform/backgroundcheck-read` | Read-only access to background check endpoints |\n| `api-platform/backgroundcheck-read-write` | Read and write access to background check endpoints |\n\n**Using the Token**\n\nInclude in all subsequent requests as `Authorization: Bearer `.\n\nTokens expire after **3,600 seconds** - cache and reuse, request a new one only when close to expiry.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret","scope"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"description":"Must be `client_credentials`."},"client_id":{"type":"string","description":"Public identifier issued during onboarding."},"client_secret":{"type":"string","format":"password","description":"Private credential issued during onboarding. Store in a vault."},"scope":{"type":"string","description":"Space-separated list of permissions. e.g. `api-platform/monitoring-read-write`\n"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Token issued successfully.\n\n**Headers:** `Cache-Control: no-store`, `Pragma: no-cache`\n","headers":{"Cache-Control":{"schema":{"type":"string"}},"Pragma":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Bad Request.\n\n`invalid_request` - `grant_type` missing or not `client_credentials`.\n\n`invalid_scope` - Scope not granted to this client.\n\n`unsupported_grant_type` - Must be `client_credentials`.\n\n`invalid_grant` - Authorization grant is invalid.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"401":{"description":"Unauthorized.\n\n`invalid_client` - Wrong `client_id` / `client_secret`, or client revoked.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"500":{"description":"Internal Server Error.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"502":{"description":"Bad Gateway.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}}},"components":{"schemas":{"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"Bearer token for API calls."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Token lifetime in seconds (3600 = one hour)."}},"required":["access_token","token_type","expires_in"]},"OAuthError":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable error code."},"error_description":{"type":"string","description":"Human-readable explanation."}},"required":["error"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.vcheckglobal.com/api-reference/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.