Authenticating to the API

Your API Credentials

Gravity Payments will provide an API Key and Secret pair for you to use in the sandbox environment, and a separate pair for the production environment. If you haven’t yet received these credentials, please reach out to our Developer Support team.

To submit accounts to the API, you will first need to retrieve an authentication token by logging in with your credentials. You’ll then use this authentication token in subsequent requests to claim your access to the API. Tokens last for 24 hours, after which time you’ll need to retrieve another.

To retrieve a token, you will POST a JSON object to the /auth endpoint as follows:


Request Body

{"action":"create","data":{"id":"{your API Key goes here}","secret":"{your API Secret goes here}"}}

This request will prompt the server to authenticate your access and respond with an authentication token. The response body after a successful request will contain a JSON object that looks like the following:

Response Body

{"isBase64Encoded":false,"statusCode":200,"headers":{"Access-Control-Allow-Origin":"*","Access-Control-Expose-Headers":"X-Access-Token, X-Session-Id, X-Request-Token","X-Access-Token":"AQICAHgcTaHL3EPq+e+7IhElLc\/QvU27H+Gh60lzKHHta73NTwF1qN6oDlRsyyJp5cGiRrOQAAAA8DCB7QYJKoZIhvcNAQcGoIHfJRfkAgEAMIHWBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDJtCkjavxnTYz79RNGQIE5DBqIAOzOgA57emTVfHVMaelio91sdxi23XLBK5P14QpsAgJ8J+ZEWOenRuBgF9hg++gJzW5IxT9TlTIZsbL+JdhdUih36UMyf\/\/sDVukoT5ycypHpSQw2WNhVByh9MQivQHfO6WYwidMgJZp+nJML9PwYplN+S8fwFOE+kK\/YT0GJcVXkdzUufHvCvzTWjrLrBtg8Tqat06zJCa8z64iR4t60L7PGIaC2ecg=="},"body":"{\"originalAction\":\"CREATE\"}"}

The important part of this object is the X-Access-Token attribute of the headers hash. This is the authentication token value that you will need to include in subsequent API requests.


Using cURL on the command line, your request would look like the following:

curl -H "Content-Type: application/json" -d '{"action": "create", "data": {"id": "{your API Key goes here}", "secret": "{your API Secret goes here}"}}'{version}/auth