# BearerAuth (JWT)

## Authenticate using OAuth 2.0 <a href="#authenticate-using-oauth-2__002e0" id="authenticate-using-oauth-2__002e0"></a>

Alternatively, OAuth 2.0 can be used together with the Client ID, Client Secret, and Scope. This information is provided during onboarding.

Using the provided credentials, you will be able to generate a JWT access token that needs to be used in all API calls.

### Prerequisites for using APIs <a href="#prerequisites-for-using-apis" id="prerequisites-for-using-apis"></a>

To authenticate with the Verifone APIs, you must obtain an access token. This access token is attached to API requests and inspected for a valid signature and expiration time when performing API calls.

## How to obtain the authentication credentials <a href="#how-to-obtain-the-authentication-credentials" id="how-to-obtain-the-authentication-credentials"></a>

You will be provided with the following details during onboarding:

* Client ID
* Client Secret (associated to the Client ID)
* Scope

Use the following links for each environment:

<table data-header-hidden><thead><tr><th width="168"></th><th></th></tr></thead><tbody><tr><td>US Production</td><td><a href="https://us.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token">https://us.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token</a></td></tr><tr><td>EMEA Production</td><td><a href="https://emea.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token">https://emea.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token</a></td></tr><tr><td>NZ Production</td><td><a href="https://nz.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token">https://nz.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token</a></td></tr><tr><td>AU Production</td><td><a href="https://au.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token">https://au.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token</a></td></tr><tr><td>Global Sandbox</td><td><a href="https://cst1.test-vam.vfims.com/oauth2/realms/root/realms/VerifoneServices/access_token">https://cst1.test-vam.vfims.com/oauth2/realms/root/realms/VerifoneServices/access_token</a></td></tr></tbody></table>

With this information combination, you can authenticate/authorize and receive the access token.

## How to obtain the access token (JWT) <a href="#how-to-obtain-the-access-token-__0028jwt__0029__000a" id="how-to-obtain-the-access-token-__0028jwt__0029__000a"></a>

The access token is formatted as a JWT (JSON Web Token).

The OAuth2.0 Client Credential grant flow is used to get the access token. Your application will need to have the Client ID and Client Secret stored securely.

Perform the following call to get your access token:

```bash
curl -k --request POST \
--data "grant_type=client_credentials" \
--data "client_id=${CLIENT_ID}" \
--data "client_secret=$CLIENT_SECRET}" \
--data "scope=${SCOPE}" \
https://cst1.test-vam.vfims.com/oauth2/realms/root/realms/VerifoneServices/access_token
```

### Request parameters

* `client_credentials` - indicating that Client Credentials grant is in use
* `scope` - must be at least one custom scope received from Verifone; in case of multiple scope values, they need to be sent as space-separated values within a single string

### Response parameters

* `access_token` - contains the access token in JWT format [RFC 7519](https://tools.ietf.org/html/rfc7519).
* `expires_in` - contains the expiration time in seconds for the access token. Once the access token expires, you should send a new request to the authorization endpoint in order to re-authenticate your application.
* `scope` - contains the list of all the scopes associated with the `access_token`.

As per [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-4.4.3), a refresh token is not provided. If the request failed client authentication or is invalid, the authorization server will return a HTTP 400 (Bad Request) status code.

**Example access token**

If the credentials are valid, the application will receive back an access token in JSON Web Token (JWT).

Example access token:

```json
eyJ0eXAiOiJKV1QiLCJ6aXAiOiJOT05FIiwia2lkIjoid1UzaWZJSWFMT1VBUmVSQi9GRzZlTTFQMVFNPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI1OWJlYjAzNy1kNjRhLTQyMjgtODM2NC0wZWQ1NDAyMDVmZDUiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXVkaXRUcmFja2luZ0lkIjoiN2NlYzIzZGItNjc1ZC00ZDJmLWFmMmYtZTkxZjQ4ZGY4NzJkLTQ3NDM2IiwiaXNzIjoiaHR0cHM6Ly9xYXQxLnRlc3QtdmFtLnZmaW1zLmNvbS9vYXV0aDIvcmVhbG1zL3Jvb3QvcmVhbG1zL1Zlcmlmb25lU2VydmljZXMiLCJ0b2tlbk5hbWUiOiJhY2Nlc3NfdG9rZW4iLCJ0b2tlbl90eXBlIjoiQmVhcmVyIiwiYXV0aEdyYW50SWQiOiJLOFF1SGFxYnpVTnhIVVVRak04d2FaRmF6bjgiLCJhdWQiOiJNYXJrZXRwbGFjZU9hdXRoIiwibmJmIjoxNTk2OTcwODc1LCJncmFudF90eXBlIjoiY2xpZW50X2NyZWRlbnRpYWxzIiwic2NvcGUiOlsibWFya2V0cGxhY2UiXSwiYXV0aF90aW1lIjoxNTk2OTcwODc1LCJyZWFsbSI6Ii9WZXJpZm9uZVNlcnZpY2VzIiwiZXhwIjoxNTk2OTcxMDU1LCJpYXQiOjE1OTY5NzA4NzUsImV4cGlyZXNfaW4iOjE4MCwianRpIjoidmtRZ01kZW03bm1VYTItT1FZeHRKM1dQMC1BIiwiZW50aXR5X2lkIjoiODEwNDlmZDEtNjEyNi00ZDQxLTg0MTYtYWEzNTZjNDk4Y2NhIiwicm9sZXMiOiJbVkVSSUZPTkVfQURNSU5dIn0.YW4MeQAMJgpLM3pOFtnx1KXJfSTTHYLklmxld8NozBuA_lQNrO9kN5Sai3MC4roOavcOYbs_TXNP2jXkOE9tNmgGUGHVtiITTIltBAJ2O7s_QCNu6v1k3tTK0-GfE5gC4I2TavwBN3nFoXmNQYbzcAh3Qetudh5A-KlsxeepeyxrLfj0BX2NbK5tVEisI1si7yS89aBJvEvCGcKTw5Ujte8naYZCGUJJUIaE2HXk-DGCNdNpmFD9_hnoDWKnN9n3ABuUW4Z6LoAW0J-BgKpuO6BroweL8fiCWYHV79f_0hCbm7sUqBmcal9j7pc4J2luy0k7TxOexHfry7w2JbpTBQ
```

To inspect the token, you can use [Jwt.io](https://jwt.io/) or you can use the [jwt command line tool](https://www.npmjs.com/package/jwt-cli).

```bash
$ cat Token.txt | xargs  jwt decode
Token header
------------
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "wU3ifI23aqasB/FG6eM1P1QM="
}
Token claims
------------
{
  "aud": "VerifoneOauth",
  "auditTrackingId": "7cec23db-555-6666-7777-999999999-47436",
  "authGrantId": "K8QuHaqbzUJAQWSM8waZFazn8",
  "auth_time": 1596970875,
  "cts": "OAUTH2_STATELESS_GRANT",
  "entity_id": "81049fd1-6126-4d41-8416-aa356c498cca",
  "exp": 1596971055,
  "expires_in": 180,
  "grant_type": "client_credentials",
  "iat": 1596970875,
  "iss": "https://cst1.test-vam.vfims.com//oauth2/realms/root/realms/VerifoneServices/access_token",
  "jti": "vkQgMdem7nmUa2-OQYxtJ3WP0-A",
  "nbf": 1596970875,
  "realm": "/VerifoneServices",
  "roles": "[VERIFONE_TEST]",
  "scope": [
    "verifoneScope"
  ],
  "sub": "59beb037-d64a-4228-8364-0ed540205fd5",
  "tokenName": "access_token",
  "token_type": "Bearer"
}
```

### Access Token Format

Obtained Access Token is in JWT format \[[RFC 7519](https://tools.ietf.org/html/rfc7519)].

#### Header

<table><thead><tr><th width="40">#</th><th width="94.5999755859375">Claim</th><th width="251.5999755859375">RS256</th><th>Claim type</th></tr></thead><tbody><tr><td>1</td><td>"alg"</td><td>RS256</td><td>Registered</td></tr><tr><td>2</td><td>"typ"</td><td>JWT</td><td>Registered</td></tr><tr><td>3</td><td>"kid"</td><td>Key Identifier (1ee4d9e7dcfef215d133c7ed7ac87c95f8d8e712)</td><td>Registered [<a href="https://tools.ietf.org/html/rfc7515#section-4.1.4">RFC7515</a>]</td></tr></tbody></table>

#### Payload

<table><thead><tr><th width="49">#</th><th width="114">Claim</th><th>Content</th><th width="293">user ID</th><th>Claim type</th></tr></thead><tbody><tr><td>1</td><td>"sub"</td><td>"5f8a9877-965c-4d25-bc86-45d1cfc1c324"</td><td>Subject (User UUID)</td><td>Registered</td></tr><tr><td>2</td><td>"entity_id"</td><td>"a4994358-a475-4ee2-aefe-acefd622991c"</td><td>User associated Entity_id. The Entity ID can be found in Verifone Central under <em>Administration → Organisations</em>. The 'Organisation ID' listed is the Entity ID.</td><td>Private</td></tr><tr><td>3</td><td>"iss"</td><td>"<a href="https://identity.vfims.com/oauth2/realms/root/realms/MerchantApp">https://identity.vfims.com/oauth2/realms /root/realms/MerchantApp</a>"</td><td>Issuer</td><td>Registered</td></tr><tr><td>4</td><td>"aud"</td><td>"Verifone View"</td><td>Audience - recipient for which the JWT is intended</td><td>Registered</td></tr><tr><td>5</td><td>"iat"</td><td>1516239022</td><td>Issued At Time</td><td>Registered</td></tr><tr><td>6</td><td>"exp"</td><td>NumericDate value</td><td>Expiration Time</td><td>Registered</td></tr><tr><td>7</td><td>"nbf"</td><td>1568783970</td><td>(Not Before Time) - Time before which the JWT must not be accepted for processing</td><td>Registered</td></tr><tr><td>8</td><td>"roles"</td><td>["MERCHANT_REVIEWER", "MERCHANT_DEVELOPER"]</td><td>User associated role(s)</td><td>Private</td></tr><tr><td>9</td><td>"jti"</td><td>TO6JCVdqS4hJB3_DzVurB3HOe9s</td><td>(JWT ID) - Unique identifier; can be used to prevent the JWT from being replayed</td><td>Registered</td></tr><tr><td>10</td><td>"scope"</td><td>Merchant Scope</td><td>Scopes (limit the API category that can be accessed)</td><td>Registered</td></tr><tr><td>11</td><td>"auditTrackingId"</td><td>cbadf943-c28c-450b-bd53-ef11c2b7d80c-17881178</td><td>AM correlation to audit trail</td><td>Private</td></tr><tr><td>12</td><td>"auth_level"</td><td>0</td><td>AM Authentication level</td><td>Private</td></tr><tr><td>13</td><td>"tokenName"</td><td><strong>access_token</strong></td><td>Token description</td><td>Private</td></tr><tr><td>14</td><td>"realm"</td><td>"/MerchantApp"</td><td>AM authentication realms</td><td>Private</td></tr></tbody></table>

#### Signature

The result of the following computation:

```apache
JWT_Hash = SHA256(Header + Payload)
JWT_Signature = RS256(JWT_Hash, Private_key)
```

### Using the JWT to authenticate in API calls

Once a access token has been obtained, this must be used in all API requests to any of the Verifone APIs.

This can be done by sending the access token as bearer token in the Authorization HTTP header.

```json
curl https://gsc.verifone.cloud/oidc/api/v2/transactions
   -H "Accept: application/json"
   -H "Authorization: Bearer {token}"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.verifone.com/online-payments/api-integration-methods-auth-and-endpoints/api-authentication/authentication-methods-basic-and-bearer/bearerauth-jwt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.