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