Whenever a magic link, one-time passcode or OAuth token is authenticated, our verify endpoints (VerifyMagicToken, VerifyOTP, and VerifyOAuthToken endpoints) allow an option to issue a session token if a session_expires_in parameter is set. session_expires_in will extend or set the duration of this current session to the specified number of minutes from now. This session will be associated with the method of authentication used and the user who has successfully authenticated.

To take advantage of our session management, we recommend that you store this token on client-side in localStorage or cookie verify this token for every sensitive action. For example, you should implement within your middleware or an endpoint on your backend/server-side to call our API to verify this session token whenever an action requires authorization check to ensure that this session is valid and not deleted.

All of our session endpoints require your secret ApiKey and hence should be used and implemented in your backend/server-side. Please ensure that you NEVER expose your ApiKey

​
Start session

All of our verify endpoints (VerifyMagicToken, VerifyOTP, and VerifyOAuthToken endpoints) allow an option to issue a session token if a session_expires_in parameter is set. session_expires_in will extend or set the duration of this current session to the specified number of minutes from now. A session must be a minimum of 5 minutes and maximum of 366 days from the time it is set. You should then store this session_token on the client-side via localStorage or cookie.

​
Verify session and extend session

In your backend/server-side, we recommend that you implement a middleware or an endpoint on your backend/server-side to call our API to verify this session token whenever an action requires authorization check to ensure that this session is valid and not deleted. If a session is still valid, we will return the user_id associated with the session, which can be used in your backend with GetUser to retrieve the other associated identifiers such as phone numbers, emails, and wallets. When a session_token is invalid, please immediately delete and clear this token from the client-side and return unauthorized response to your user.

​
Extend Session

If you wish to extend an existing session, the VerifySession endpoint allows you to use session_token and session_expires_in parameters to extend an existing session N number of minutes from now.

Our VerifySession endpoint should only be used from your backend/server side using your secret ApiKey. Please ensure that you NEVER expose your ApiKey.

cURL
curl -L -X POST 'https://api.streambird.io/v1/auth/sessions/verify' \
-H 'Authorization: Bearer sk_test_pRqweh3wvWmJAAVYv7Z0T5iPLzFM4ql0muoyQcjOxGeN3p1r' \
-H 'Content-Type: application/json' \
--data-raw '{
    "session_token": "vy9YGpubKjVn98cw1nT25Msj7jaIpHBinUfD45KLdAOgn9NqEuE4qGHOEchEG5Ue",
    "session_expires_in": 10080
}'

​
Delete and sign out of a session

You can sign out of a session using our DeleteSession endpoint, which will invalidate the session_token sent in. As a best practice, we recommend that you show a list of sessions using our ListSession endpoint, which allows you to get a list of active sessions tied to the specified user_id (an example UI is provided below for reference).

cURL
curl -L -X DELETE 'https://api.streambird.io/v1/auth/sessions/delete' \
-H 'Authorization: ApiKey sk_test_pRqweh3wvWmJAAVYv7Z0T5iPLzFM4ql0muoyQcjOxGeN3p1r' \
-H 'Content-Type: application/json' \
--data-raw '{
    "session_token": "vy9YGpubKjVn98cw1nT25Msj7jaIpHBinUfD45KLdAOgn9NqEuE4qGHOEchEG5Ue"
}'
OverviewSession Token vs JWT