Access Tokens

Requesting an Access Token

To request an access token you will need to make a request with the createOAuthAccessTokenFromClientCredentials mutation using a client id and client secret as the authorization for your reqeust. These values can be found in the Control Panel.

Once obtaining the client id and secret for your application, base64 encode the value and include it in the authorization header.

echo -n 'CLIENT_ID:CLIENT_SECRET' | base64

"Authorization": "Basic BASE64_ENCODED(CLIENT_ID:CLIENT_SECRET)"

Access Token Scopes

When requesting an access token you must pass in the scopes needed to perform the mutations and queries where the access token will be used as the authorization.

Mutation

mutation createOAuthAccessTokenFromClientCredentials(
  $input: CreateOAuthAccessTokenFromClientCredentialsInput!
) {
  createOAuthAccessTokenFromClientCredentials(input: $input) {
    accessToken {
      accessToken
      tokenType
      expiresAt
    }
  }
}

Variables

{
  "input": {
    "scopes": [
      "TRANSACTION_SALE",
      "TRANSACTION_MANAGE_SETTLEMENT"
    ]
  }
}

Using the Access Token

The access token will be available in the response of the createOAuthAccessTokenFromClientCredentials mutation.

Response

{
  "data": {
    "createOAuthAccessTokenFromClientCredentials": {
      "accessToken": {
        "accessToken": "access_token$sandbox$abc123",
        "tokenType": "BEARER",
        "expiresAt": "date"
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Authorization with an Access Token

To authenticate with an access token, take the access token from the response and include it in the authorization header.

"Authorization": "Bearer ACCESS_TOKEN"

Call the subsequent mutations or queries as normal.

Errors

If the scopes used to generate the access token are not sufficient for the mutation or query being called, an authorization error will be returned.

Response

{
  "extensions": {
    "errorClass": "AUTHENTICATION",
    "errorType": "developer_error"
  },
  "message": "Authentication credentials are invalid."
}

Mutations and the scopes needed

This is a list of the minimum required scopes for certain mutations.

Note

The required scopes for a mutation may increase or descrease depending on the fields requested in the mutation.

Mutation	Scope
authorizeCreditCard	TRANSACTION_SALE
authorizePaymentMethod	TRANSACTION_SALE
authorizeVenmoAccount	TRANSACTION_SALE
captureTransaction	TRANSACTION_MANAGE_SETTLEMENT
chargeCreditCard	TRANSACTION_CHARGE
createCustomer	CUSTOMER_CREATE
createVenmoPaymentContext	PAYMENT_CONTEXT_CREATE
Node.venmoPaymentContext	PAYMENT_CONTEXT_FIND
partialCaptureTransaction	TRANSACTION_MANAGE_SETTLEMENT
refundTransaction	TRANSACTION_REFUND
reverseTransaction	TRANSACTION_REVERSE
tokenizeCreditCard	SINGLE_USE_PAYMENT_METHOD_CREATE
tokenizeNetworkToken	SINGLE_USE_PAYMENT_METHOD_CREATE
vaultPaymentMethod	PAYMENT_METHOD_VAULT

List of all available scopes

This is a list of the available scopes in the API. Please note that this list is subject to change.

ADDRESS_CREATE ADDRESS_DELETE ADDRESS_FIND ADDRESS_UPDATE APPLE_PAY_MANAGE_WEB_DOMAINS CLIENT_TOKEN_GENERATE CREDIT_CARD_EXPIRING_BETWEEN CREDIT_CARD_VERIFICATION_SEARCH CUSTOMER_CREATE CUSTOMER_DELETE CUSTOMER_FIND CUSTOMER_SEARCH CUSTOMER_UPDATE DISPUTE_ACCEPT DISPUTE_ACCEPT_FACILITATED DISPUTE_ADD_EVIDENCE DISPUTE_ADD_EVIDENCE_FACILITATED DISPUTE_FINALIZE DISPUTE_FINALIZE_FACILITATED DISPUTE_FIND DISPUTE_FIND_FACILITATED DISPUTE_REMOVE_EVIDENCE DISPUTE_REMOVE_EVIDENCE_FACILITATED DISPUTE_SEARCH DISPUTE_SEARCH_FACILITATED DOCUMENT_UPLOAD_CREATE GRANT_PAYMENT_METHOD MERCHANT_ACCOUNT_ALL MERCHANT_ACCOUNT_FIND MULTI_USE_PAYMENT_METHOD_CREATE MULTI_USE_PAYMENT_METHOD_DELETE MULTI_USE_PAYMENT_METHOD_FIND MULTI_USE_PAYMENT_METHOD_UPDATE PAYMENT_CONTEXT_CREATE PAYMENT_CONTEXT_FIND PAYMENT_CONTEXT_SEARCH PAYMENT_METHOD_VAULT PAYMENT_METHOD_VERIFY READ_FACILITATED_TRANSACTIONS SETTLEMENT_BATCH_SUMMARY_GENERATE SHARED_VAULT_TRANSACTIONS SINGLE_USE_PAYMENT_METHOD_CREATE SINGLE_USE_PAYMENT_METHOD_FIND SUBSCRIPTION_CANCEL SUBSCRIPTION_CREATE SUBSCRIPTION_FIND SUBSCRIPTION_SEARCH SUBSCRIPTION_UPDATE TRANSACTION_CHARGE TRANSACTION_FIND TRANSACTION_MANAGE_SETTLEMENT TRANSACTION_REFUND TRANSACTION_REVERSE TRANSACTION_SALE TRANSACTION_SEARCH TRANSACTION_VOID