Session-Storage

It can be challenging to create user authentication without the ability to create deep links between applications. For instance, when setting up a Discord bot to authenticate users, either the bot must have a public URL that is accessible on the internet or the user must manually enter their information.

If neither of these options is feasible (or desired), it becomes difficult to trigger a successful authentication and access the necessary information because the separation prevents incoming triggers. Instead, a pull or polling method must be used to retrieve the information until the process is completed.

Sessions provide the ability to initiate an authentication process and watch its status using a polling technique.

The complete OpenAPI Documentation is available on: https://app.vechain.energy/docs/api/auth (opens in a new tab)

Initialize Session

Every session is identified by a unique alphanumeric session id with a temporary lifetime of 10 minutes.

The session id is generated by the client. The state used during authentication is posted as JSON object to the endpoint.

Prompting User-Authentication

The user is linked to the authentication with the following requirements:

1. the state must be identical to the one posted with the session
2. the redirectUri must be https://auth.api.vechain.energy/session/{sessionId} (replace {sessionId} with the generated session id)

Session Status

Once the user is authenticated the redirect will automatically fetch the token information from /oauth2/token and save the raw result in the session storage.

GET /session/{sessionId} returns the raw json object and should be polled until an access_token or error attribute is present.

Session Removal

Sessions will be automatically deleted. If an earlier removal is required, DELETE /sessions/{sessionId} is available.