Authentication In Depth

Vanguard endpoints

The Vanguard REST API base url is different for the different execution environments.

Sandbox Vanguard url

https://vanguard.sandbox.waya.se/v2.0

Production Vanguard url

https://auth.waya.se/vanguard/v2.0

Creating and signing a JWT token

The token needs the following fields.

Field	Value
Issuer	<issuer-url>
Header parameter "kid"	<key-id>
Claim "iid"	<integration-id>
Issued at	Creation time in seconds since Unix epoch (1970-01-01)
Expiring at	Expiration time in seconds since Unix epoch (1970-01-01)

The Key Material is a base64url encoded string which need to be decoded before signing the token. Use the HS512 algorithm. See the java code below for an example of how to create and sign a JWT token.

Note: There is a difference between base64url and base64 encoding. Some languages handles only base64, in those cases you'll have to do the url decoding bit yourself.

package utils;

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Base64;
import java.util.Date;

public class Utils {
 public static String createJwtToken(String integrationId, String issuerUrl, String keyId, String keyMaterial, int expiration) {
  return Jwts.builder()
   .setIssuer(issuerUrl)
   .setHeaderParam("kid", keyId)
   .claim("iid", integrationId)
   .setIssuedAt(Date.from(Instant.now()))
   .setExpiration(Date.from(Instant.now().plus(expiration, ChronoUnit.MINUTES)))
   .signWith(Keys.hmacShaKeyFor(Base64.getUrlDecoder().decode(keyMaterial)))
   .compact();
  }
}

Getting an authentication token

A authentication token is created by making an HTTP POST request to the /authentications/integrations endpoint. The body should contain a JSON object with the key subject set to your JWT token. See example using curl below.

curl --request POST \
  --url '<vanguard-url>/authentications/integrations' \
  --header 'Content-Type: application/json' \
  --data '{ "subject": "<jwt-token>" }'

This will return a JSON object containing the authentication token if successful.

{
	"token": "<authentication-token>",
	"error": null
}

The authentication token can be long-lived and used to authorize multiple accounts.

Authorizing an account

Look up account id

If you know the account id you want to authorize, you can skip this step and continue with account authorization below.

If you haven't received an account ID from Waya or if you want to use another account. To find the account ids you can then use the endpoint /organizations. The request needs an Authorization header set to Bearer <authentication-token>.

curl --request GET \
  --url '<vanguard-url>/organizations' \
  --header 'Authorization: Bearer <authentication-token>'

If successful you will get a list of accounts with IDs you can use:

{
  "result": {
    "count": 1,
    "totalCount": 1,
    "more": false,
    "organizations": [
      {
        "id": "someOrganizationId",
        "name": "Company AB",
        "accounts": [
          {
            "id": "someAccountId",
            "name": "Company AB",
            "user": null,
            "credentials": null
          }
        ]
      }
    ]
  },
  "error": null
}

Authorization

To authorize an account, you need to call the endpoint /authorizations with a query parameter accountId set to the <account-id> you want to authorize. The request needs an Authorization header set to Bearer <authentication-token>. See example using curl below.

curl --request POST \
  --url '<vanguard-url>/authorizations?accountId=<account-id>' \
  --header 'Authorization: Bearer <authentication-token>'

If successful this will return an authorization token for this account.

{
	"token": "<authorization-token>",
	"error": null
}

Note: The authentication token typically lasts a week before expiration. The authorization token typically lasts 24 hours.