Introduction

A user access tokens is used to access API endpoints which do require a logged in user or applicant. The token expires after 60 minutes (3600 seconds) if it is not used in the meantime.
A user access token builds upon a client access token, hence allows access to all client token endpoints as well.
It is delivered as a string of at least 32 characters length.

Workflow to receive a user access token

Via shell

The {idPwdCombo} variable is the combination of your registered applications ID and the according passwort, noted as follows: “id:password”, e.g. “42:raNDomPasSWORd”. {applicantLogin} and {applicantPwd} represent the applicants login credentials. The parameters of curl’s -d flag would for example look like that: -d ‘grant_type=password&username=joe.doe%40foo.bar&password=blink182’ . Please note that the username and password may contain special characters which need to be urlencoded on their own – please do not urlencode the whole String.

A complete example call could like that:

Example response

Behavior upon unsuccessful verification

User access tokens (abbreviate UAT below) are key components inside the API’s structure, most functions start by validating the passed token. Upon failure of this validation, an appropriate HTTP response is constructed. For most problems, an error as well as error_description field are added to the header describing the issue.

Upon Response Code Description error error_description remarks
no UAT given 401 UNAUTHORIZED n/a n/a no error and error_description
invalid or expired UAT 401 UNAUTHORIZED “invalid token” “token expired or otherwise invalid” n/a
UAT misses scope 403 FORBIDDEN “insufficient_scope” “valid token with insufficient scope” n/a
token was only CAT 401 UNAUTHORIZED “invalid_token” “user token required, but client token sent” n/a

Comments

Comments are closed.