AuthenticationApi

Authentication using JWT Allows clients to authenticate and acquire an access token using a JSON Web Token.

If successful, the response includes a user or client access token which can be used as a session token for other authenticated endpoints in the Sensibill API.

There are two types of access tokens - user tokens and client tokens. Passing in your clientID in the 'sub' claim (or individual ID claim field) of your JWT will return a client access token. Passing a user's access ID in your ID Claim field will return a user access token instead.

Your client account must be configured to allow JWT (please reach out to the Sensibill Support Team). The API supports JWS and JWE as JWT implementations.

JWS currently supports RSA and ECDSA signing algorithms (RS256, RS384, RS512, ES256, ES384, ES512). Public keys for signature verification should be made available through a publicly accessible URL. JWS header must have 'alg' and 'kid' parameters and the payload must have at least 'sub' and 'iat' claims. The 'sub' claim is used to identify either a user or a client. If there is a desire to use another claim for those purposes then it can be configured during the client account setup. JWS implementation also supports 'exp', 'aud', 'iss' and 'scp' claims. If there is a need to validate those claims they should be configured as part of the client account setup.

JWE currently supports RSAES OAEP using default parameters ('alg': RSA-OAEP) for encrypting the Content Encryption Key (CEK) and AES GCM using 256-bit key ('enc': A256GCM) for encrypting the content. Please reach out to the Sensibill Support Team to receive Sensibill’s public key to be used for JWT encryption. JWE’s content is expected to be a JWS conforming to the JWS requirements mentioned earlier.

The response also returns a token_id. This can not be used for authenticating regular requests, but is required for using our query parameter based signature method. Responses:

Obtain an Access Token Allows a client to use its credentials to obtain an access token, to swap an authorization grant for an access token, or to swap a refresh token for a new access token. There are two types of access tokens - user tokens and client tokens.

A client token authenticates a specific client, e.g. your architecture and servers. client tokens can be used to access any resources owned by the client, such as general information on users your client has created. Client tokens are also required to register new users or make requests on their behalf such as the user posting a receipt.

A user token authenticates a specific user to our system, e.g. Jane Doe of Winnipeg, Manitoba. A user token will be required if you want to access specific data about a user, such as the details of that user's documents.

Token expiry information is in the `expires_in` and `refresh_expires_in` fields.

You can also retrieve the expiration times for user and client access tokens using the user GET endpoint, `/users/:userID`, and the clientInfo GET endpoint, `/clientInfo`, respectively.

No matter which kind of access token is being requested, the client MUST include their Client Key and Client Secret as the username and password, respectively, in the HTTP Authorization header, on top of providing required parameters below.

This can be accomplished by setting a 'basic' authentication header using the Client Key and Client Secret as username and password like shown below:

`Authorization: 'Basic base64(ClientKey:ClientSecret)'`

The access token is currently always a bearer token, which should be sent in the 'Authorization' header in the format 'Bearer accessToken'.

In the future, other token types may also be used, so please check the `token_type` provided in the response.

For an example, please refer to 'Authentication Step Six' of the jQuery Demo.

The response also returns a `token_id`. This can not be used for authenticating regular requests, but is required for using our query parameter based signature method. Responses:

Request an authorization grant Allows clients to request an authorization grant to begin the OAuth2 flow. As an OAuth2 endpoint, all of the parameters and result variables from this endpoint have names that use underscores, versus the rest of the API which is camel-cased.

Clients must provide a username and password in the Authorization header of the request (or equivalent accessID, accessSecret and credentialType for SSO clients). This can be accomplished by setting a 'basic' authentication header using the user's username and password in compliance with Section 2 of RFC 2617 like shown below:

`Authorization: 'Basic base64(username:password)'`

Types of secrets

Sensibill supports 2 modes of operation for client secrets:

In the case where a client can guarantee a secret that is closely guarded, it allows for user administration support (e.g, deactivate, reactivate users, etc)
In the case where the secret may not be so secret ie. embedded in an application, the administrative actions are not allowed.

For an example, please refer to 'Authentication Step Five' of the jQuery Demo. Responses:

Client information Allows a client to retrieve information about itself. You can use this endpoint with the client's OAuth key and secret using Basic authentication, with a client access token, or with a user access token. When using a client access token, the response also includes the expiration time for the token used. Responses:

Invalidate access token This endpoint can be used to permanently invalidate an access token. Simply POST to this endpoint using a normal authenticated request, and whatever access token was used in the request will be invalid for any further requests. Responses:

Logout user Performs a user logout, clearing the session and invalidating the access token. Works similarly to /invalidate, but simply as a GET call. Responses: