When and how do I setup a Custom Client Auth token in the API? – Hydrogen

What is the use case for the Custom Client Auth Token?

The Custom Client Auth Token is useful when you want to authenticate a user on the Hydrogen APIs and the following criteria are met:

You already have a credentialing system in place for users; AND
You don’t wish to store the user’s password with Hydrogen, or use our OAuth 2.0 password grant.

A common use case for the Custom Client Auth Token is when you have an existing user base on a mobile or web app. This type of authorization validates a user’s permission to access their data, while allowing you to maintain the login credentials for the user.

PLEASE NOTE: IF YOU ARE USING A HYDROGEN WHITE LABEL APP (e.g. HYDROGEN CARDS WHITE LABEL WEB APP), THIS AUTH IS NOT NECESSARY. BY DEFAULT WE WILL BE MANAGING ALL USER LOGINS AND SIGNUP CREDENTIALS.

How do I setup and use the custom JWT token?

SETUP

The custom token flow consists of exchanging a signed payload with a private key, in addition to your client_id and your client_secret for an access_token, to be provided when making calls to the Hydrogen API. This JWT token exchange follows standards set by IETF for OAuth 2.0 Token Exchange.

Please follow the steps below to create your custom JWT token:

Create your public/private key pair. We ONLY accept a key in 2048 bit PKCS#8 encoded format. Here is a recommended site for creation in this format.
Store the private key that is created in your application securely.
Login to the Hydrogen dev portal and upload the public key that is created under “API Keys & Whitelists” in the settings dropdown on the top right. All line breaks and spaces will be trimmed after submission.
For each user, you will need to store the username in the Nucleus Client. YOU DO NOT NEED TO STORE THE PASSWORD. If you wish to use Hydrogen to store passwords, you will use the Resource Owner Password Credentials OAuth flow instead.

TOKEN CREATION

To authenticate the user, simply sign the following payload using your private key. See example code for the language of your choice on our documentation here.

{
    ”sub”: “Client username“,
    ”iss”: “OAuth client_id“,
    ”exp”: The epoch time the token expires,
    ”iat”: The epoch time the token is issued
}

Algorithm and token type
{
”typ”: “JWT”,
”alg”: “RS512”
}

After signing the payload, you can now submit the payload as a Basic Header, along with a Basic Base64 encoded client_id and client_secret. The response should now give you the same access_token as a password grant, and you can use this to call all subsequent Hydrogen APIs for this user.

Learn More

What are the user authentication password options in the API?

What OAuth 2.0 grant types does Hydrogen accept in the API?