Concept
The Integration Services API uses JSON Web Tokens (JWTs) as a secure way to authenticate yourself. First, you must sign a nonce (number only used once) generated by the API with your secret key to obtain a JWT. Afterwards, the API verifies the signed nonce and returns a JWT.
Authentication Workflow
1. Request a Nonce
First, you must request the nonce via a get request to the endpoint. Provide the identity id to authenticate in the URL. You can find more information in the API Reference.
GET /authentication/prove-ownership/<identity-id>
JSON response body:
{
"nonce": "748fd25be77773dbce248779e4982b6759f84071"
}
2. Hash the Nonce
Once you have received your nonce, you should hash it using SHA-256 and encode it to hexadecimal to sign it afterwards.
3. Sign the Hashed Nonce
You can now sign the hashed nonce with your secret key. Your secret key is encoded in Base58 and needs to be decoded to hexadecimal. You can sign your hashed nonce with your decoded secret key using the Ed25519 algorithm. Make sure that the signed nonce is in hexadecimal.
4. Request the JWT
You can request your JWT using the /authentication/prove-ownership/<identity-id> endpoint. It is the same endpoint as in the first step, but it uses the POST method instead of GET. You should add your signed nonce in the request body. You can find more information in the API Reference.
POST /authentication/prove-ownership/<identity-id>
JSON request body:
{
"signedNonce": "9606885340235e37d43..."
}
JSON response body:
{
"jwt": "eyJhbGciOiJIUzI1NiI..."
}
5. Use the JWT in a Header
For all following requests to endpoints protected by authentication use your JWT in the Authentication header with the prefix Bearer: Authentication: Bearer eyJhbGciOiJIUzI1NiI...