Generate an authorization Token (2024)

Generate an authorization Token

Guidance on using both an API Key and a signing key is included in the instructions below. Follow the steps for your preferred authentication key.

If you will use an API key for authentication:

1. Open secret.txt in the location to which you saved it and copy the key.
2. Paste it in the field provided.
3. Provide the required sample Parameters requested.
4. Click Generate to produce a corresponding Token.io web app URL.
5. Click Test to link to the Token.io web app and see the UI that will be presented to a customer.

   

Finally, remember where you stored secret.txt on your local machine in accordance with the instructions above, because you'll need to include your API key in the authorization header for certain methods, as explained in the guidance for each respective service type (AIS, PIS, and CAF).

If you will use signing for authentication:

1. Select the public key you uploaded and want to use from the drop-down list under Choose Key ID.
2. Provide the required sample Parameters requested to populate the request payload (see table).
3. Click Copy Payload, then use your preferred signing tool to paste the payload, add your private key, and generate a signature. Here's how:

   First, construct the HttpAuthPayload and normalise the JSON string. Here's an example:

   {"createdAtMs":"1585871575757","method":"POST","queryString":"type=access","requestBody":"{\"params\":{\"requestId\":\"rq:37F1Ufy6Zw6o7ZYQktTaDFheq91q:5zKtXEAq\",\"resourceTypeAcce ss\":{\"accountIdentifiers\":[\"IRONUSCA000|iban:15858715675463587689\",\"IRONUSCA000|iban :15858715691926450293\"]}\"userId\":\"m:2Uz1duWzpqQ8qhJzSDFvA6Gkb Fm1: 5zKtXEAq\"}}","uriH ost":"api.dev.token.io:443","uriPath":"/banks/iron/consents"}

   There are three essential rules for normalising JSON strings:

   See Also

   Pros and Cons of Using Token-based AuthenticationToken-Based Authentication - Secret Double OctopusToken Based Authentication in ASP.NET Web APIExploring Token-Based and Session-Based Authentication: Understanding the Differences

   (a) Keys must be in alphabetical order

   (b) Keys must be enclosed in double quotes

   (c) No spaces and no new line (line return).

   Here's example code in Java on how to automate the normalisation process in production to ensure accurate results:

   Java

   /**

   * sorts a JSON string into a string with keys ordered alphabetically (recursive)

   * relies on internal LinkedHashMap to maintain the order of keys

   *

   * @param input JSON string to sort

   * @return sorted JSON string

   */

   public static String sort(String input) {

   JsonElement parsed = new JsonParser().parse(input);

   Object sorted = sortJsonElement(parsed);

   return new GsonBuilder()

   .disableHtmlEscaping()

   .create()

   .toJson(sorted);

   }

   SOURCE ↗

   Otherwise, major HTTPAuthPayload components comprise the following:

   Payload Item	Description
   createdAtMs	Timestamp of request creation in milliseconds; ex. 1 day (24 hours) = 86400000, 1 hour = 36000000, and 1 minute = 60000
   method	HTTP method; i.e., GET, POST, PUT, or DELETE
   queryString	Query in your request; e.g., "type=access"
   requestBody	JSON body string of your request; must be normalised and is required if performing POST or PUT.
   uriHost	Host environment of your request; e.g., Token sandbox = "api.sandbox.token.io:443"
   uriPath	Path of your request; e.b., "/banks/iron/consents"

   Everything except the timestamp is generated for you by the dashboard's Payload Builder. After constructing this payload in your preferred signing tool, use your private key to sign the payload.

4. Copy the signature generated by your signing tool, then return to the dashboard and enter it in the Paste Signature field below the payload.
5. Click Generate to produce a corresponding Token.io web app URL.Here's what you'll see:

   

6. Click Test to see what your customer will see on redirect to the Token.io web app; click Copy URL to file it away elsewhere for reference.

Important: You must include a valid Authentication Key (API Key or key-id and signature) in the authorization header of each API request call, where required.