Payments Public API Authentication Service
Switch branches/tags
approved-alpha_staging-1 approved-alpha_staging-1-19 approved-alpha_staging-1-17 approved-alpha_staging-1-15 approved-alpha_staging-1-14 approved-alpha_staging-1-13 approved-alpha_staging-1-12 approved-alpha_staging-1-11 approved-alpha_release-29 approved-alpha_release-28 approved-alpha_release-26 approved-alpha_release-25 approved-alpha_release-24 approved-alpha_release-23 approved-alpha_release-22 approved-alpha_release-21 approved-alpha_release-20 approved-alpha_release-19 approved-alpha_release-18 approved-alpha_release-17 approved-alpha_release-16 approved-alpha_release-14 approved-alpha_release-13 approved-alpha_release-12 approved-alpha_release-11 approved-alpha_release-5 approved-alpha_release-2 approved-alpha_release-1 alpha_test-12-migration-1 alpha_staging-2-migration-1 alpha_staging-2-70 alpha_staging-2-69 alpha_staging-2-68 alpha_staging-2-67 alpha_staging-2-66 alpha_staging-2-63 alpha_staging-2-62 alpha_staging-2-60 alpha_staging-2-58 alpha_staging-2-56 alpha_staging-2-55 alpha_staging-2-52 alpha_staging-2-51 alpha_staging-2-50 alpha_staging-2-49 alpha_staging-2-48 alpha_staging-2-47 alpha_staging-2-46 alpha_staging-2-41 alpha_staging-2-39 alpha_staging-2-38 alpha_staging-2-36 alpha_staging-2-34 alpha_staging-2-33 alpha_staging-2-29 alpha_staging-2-26 alpha_staging-1 alpha_staging-1-26 alpha_staging-1-24 alpha_staging-1-23 alpha_staging-1-22 alpha_staging-1-21 alpha_staging-1-20 alpha_staging-1-19 alpha_staging-1-17 alpha_staging-1-15 alpha_staging-1-14 alpha_staging-1-13 alpha_staging-1-12 alpha_staging-1-11 alpha_staging-0-7 alpha_staging-0-5 alpha_staging-0-2 alpha_staging-0-1 alpha_release-70 alpha_release-69 alpha_release-68 alpha_release-67 alpha_release-66 alpha_release-65 alpha_release-64 alpha_release-63 alpha_release-62 alpha_release-61 alpha_release-60 alpha_release-59 alpha_release-58 alpha_release-57 alpha_release-56 alpha_release-55 alpha_release-54 alpha_release-53 alpha_release-52 alpha_release-51 alpha_release-50 alpha_release-49 alpha_release-48 alpha_release-47 alpha_release-46 alpha_release-45
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Payments Public API Authentication Service

API Keys

Anatomy of an api key:

       TOKEN                          CHECKSUM
Item Definition
TOKEN randomly generated base 32 string, 130 bits entropy, variable length
CHECKSUM hmacSha1(TOKEN + TOKEN_API_HMAC_SECRET), base32 encoded. Always 32 characters long
TOKEN_API_HMAC_SECRET secret provided via application environment
TOKEN_DB_BCRYPT_SALT bcrypt salt provided via application environment
TOKEN_HASH bcrypt(TOKEN, TOKEN_DB_BCRYPT_SALT) - the value we actually store in the database

API KEY generation algorithm:

  1. TOKEN := 130 bit random number and encode to base32
  3. API_KEY := concat(TOKEN, CHECKSUM)
  5. store TOKEN_HASH in database
  6. return API_KEY

API KEY validation algorithm:

  1. API_KEY is provided as Authorization: Bearer someverylongstringandachecksum
  2. Extract API_KEY := someverylongstringandachecksum
  3. Split the string at a known character index based on the length of the sha1 suffix ie. TOKEN := someverylongstring ACTUAL_CHECKSUM := andachecksum
  4. verify that hmacsha1(concat(TOKEN, TOKEN_API_HMAC_SECRET)) == ACTUAL_CHECKSUM
  6. lookup TOKEN_HASH in database; return true iff found

Environment variables

DB_SSL_OPTION To turn TLS on this value must be set as “ssl=true”. Otherwise must be empty.
TOKEN_DB_BCRYPT_SALT Salt used for the hashing algorithm (bcrypt) to hash tokens before being stored in DB.
TOKEN_API_HMAC_SECRET HMAC secret to create the signature for the API Key.

Integration tests

To run the integration tests, the DOCKER_HOST and DOCKER_CERT_PATH environment variables must be set up correctly. On OS X the environment can be set up with:

    eval $(boot2docker shellinit)
    eval $(docker-machine env <virtual-machine-name>)

The command to run the integration tests is:

    mvn test

API Specification

The API Specification provides more detail on the paths and operations including examples.

Path Supported Methods Description
/v1/api/auth GET Look up the account ID for a token.
/v1/frontend/auth POST Generates a new dev token for a given account.
/v1/frontend/auth PUT Updates the description of an existing dev token.
/v1/frontend/auth/{account_id} GET Retrieves all generated tokens for this account that are not revoked.
/v1/frontend/auth/{account_id} DELETE Revokes the supplied dev token for this account.


MIT License

Responsible Disclosure

GOV.UK Pay aims to stay secure for everyone. If you are a security researcher and have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner. We will give appropriate credit to those reporting confirmed issues. Please e-mail with details of any issue you find, we aim to reply quickly.