Authentication

To authenticate, credentials are required. You can create your access credentials on the applications page of your instance.

POST /authentication

{
    "client_id": "352c8d17-5bb3-4092-95b9-4b42bd7602e1", // replace me
    "client_secret": "e3ff1063488088a3797da7379c8be52b80577d5b279e96382018d6ff58d27fee", // replace me
}

Response

{
	"data": {
		"auth_token": "a693bc712ea26984c89863f6f58c83fa10e28e3cd85d8d4991809ab19ed05fbd",
		"auth_token_expires_at": "2023-02-08T15:02:59+00:00", // UTC
		"auth_refresh_token": "26426c9e8b13ba9bb0e8a6ed0d27562a8d3a55114b4acf1f43e85de3889b29ff",
		"auth_refresh_token_expires_at": "2023-03-08T14:02:59+00:00", // UTC
		"user": {
			"id": "6238a0bb2047535156265493",
			"email": "[email protected]",
			"locale": "en",
			"first_name": "Trunkstar",
			"last_name": "Development",
			"roles": [
				"instance_admin",
				"connectivity_check"
			]
		},
		"instance_domain": "platform.trunkstar.com"
	}
}

The auth_token is used for identification on each request and is valid for 1 hour.

After the auth_token is expired, instead of sending your credentials again, you have the possibility to use auth_refresh_token.

You can create a new auth_token with the auth_refresh_token, which is valid for 1 month.

POST /authentication

{
    "auth_refresh_token": "26426c9e8b13ba9bb0e8a6ed0d27562a8d3a55114b4acf1f43e85de3889b29ff"
}

Using the auth_refresh_token has security benefits over using credentials.

Authentication token usage

The auth_token should be passed in the headers of the request under the X-Auth-Token name.

X-Auth-Token: a693bc712ea26984c89863f6f58c83fa10e28e3cd85d8d4991809ab19ed05fbd

cURL example

curl 'https://api.trunkstar.com/instances/users' \
  -H 'content-type: application/json' \
  -H 'x-auth-token: a693bc712ea26984c89863f6f58c83fa10e28e3cd85d8d4991809ab19ed05fbd'