API reference

Authentication

Access tokens and the OAuth 2.0 authorization-code flow

Every Livepush endpoint expects a JWT in the Authorization header. Tokens are issued by the auth service at https://tokens.livepush.io through the OAuth 2.0 authorization-code flow, and the three endpoints below are the whole of it.

The flow, step by step

1. Register your app at the developer console. You get a client_id, a client_secret, and a list of redirect URIs. A redirect URI sent later must match one of these exactly — there is no prefix matching.
2. Ask for consent. Call GET /oauth2/authorize with your client_id, redirect_uri, response_type=code, the scope list you need, and a random state. It returns JSON describing the consent screen rather than rendering one, so you build the UI. The sessionID it returns lives for 5 minutes.
3. Send the decision back. POST /oauth2/authorize with session_id and is_rejected. The response is a 301 to your redirect URI carrying either code and state, or error and error_description. Check state matches what you sent.
4. Exchange the code. Call GET /oauth2/access_token with grant_type=authorization_code, the code, your client_id, client_secret and the same redirect_uri. You get an access_token valid for 14 days and a refresh_token. The code is single-use and expires after 10 minutes.
5. Call the API. Send Authorization: Bearer <access_token> on every request, whatever token_type says.
6. Refresh before day 14. Same endpoint with grant_type=refresh_token, passing the refresh token in the code parameter. Refresh tokens are single-use, so store the new one from every response.

The Authentication guide covers scopes, error codes and a shortcut for getting a token while you are just experimenting.

3 endpoints