# OAuth Authentication

This section explains how authentication works when interacting with the Livepush REST API and how to obtain and use access tokens securely.

Authentication with the Livepush API is based on OAuth 2.0 and requires a registered OAuth application.

## Overview

Getting started with the Livepush REST API begins with a client request that is authenticated using OAuth credentials.

The authentication process involves:

- Registering an OAuth application to obtain a Client ID and Client Secret
- Requesting an access token with specific scopes
- Sending the access token with each API request to authenticate the user


Only authenticated requests are allowed to interact with Livepush API resources.

## OAuth 2.0

The only supported method of API authentication is OAuth 2.0.

The Livepush REST API is built on top of the standard OAuth 2.0 protocol and follows the RFC 6749 specification. This makes the API compatible with a wide range of OAuth libraries and SDKs across different programming languages and frameworks.

A detailed walkthrough of the OAuth authorization flow is provided in the Getting Access Tokens section below.

## Registering OAuth Applications

Before making authenticated API requests, you must register an OAuth application in the Livepush Developer Console.

Registering an OAuth application allows you to generate Client API Keys that are required for authentication.

### Steps to register an OAuth application

1. Log in to the Livepush Developer Console
2. Navigate to **Apps**
3. Click **New App** from the action bar
4. Enter a name for your application and click **Create App**
5. Select the newly created app and click **Manage App**
6. Copy the **Client ID** and **Client Secret** and store them securely


Always keep your Client ID and Client Secret confidential. Do not expose them in public repositories, client-side code, or public forums.

## Scopes and Permissions

Access tokens are issued with specific scopes that define what actions an application is allowed to perform.

Scopes limit the permissions of access tokens so that applications can only access the resources they are explicitly authorized for.

### Accounts API scopes

- `profile.read`
Read user profile information
- `profile.write`
Update or modify user profile information
- `subscriptions.read`
Read user subscription details
- `auth.modify`
Modify user authentication details
- `billing.read`
Read billing data such as invoices and payments
- `teams.read`
Read team-related data
- `teams.write`
Modify team-related data


### Streams API scopes

- `regions.read`
Retrieve the list of available regions
- `streams.read`
Read user stream data
- `streams.write`
Update existing stream data
- `streams.create`
Create or deploy new streams
- `streams.delete`
Delete or destroy streams
- `streams.videos.read`
Read stream video data
- `streams.videos.write`
Update or delete stream video data
- `streams.destinations.read`
Read and list stream destinations configured for a stream
- `streams.destinations.write`
Create, update, and remove stream destinations for a stream


## Getting Access Tokens

Access tokens are required for all authenticated API requests.

The Livepush API server validates the access token included in each request to identify the user and verify permissions.

To obtain an access token, your application must complete the OAuth Authorization Code flow.

### OAuth Authorization Code Flow

A typical authorization flow follows these steps:

1. The client application redirects the user to the Livepush OAuth authorization page
2. The user reviews and approves the requested permissions
3. The user is redirected back to the client application's configured redirect URI
4. The redirect URL includes a query parameter `code`
5. The client application exchanges the authorization code for an access token
6. The API returns an access token and refresh token


If the user denies authorization, the redirect URL will contain an `error` query parameter instead of `code`.

## Authorization Endpoints

### Step 1: Authorize the user

Send the user to the OAuth authorization endpoint:

`GET https://id.livepush.io/oauth2/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code&scope=<comma_separated_scopes>`

### Step 2: Exchange code for access token

Exchange the authorization code for an access token:

`GET https://tokens.livepush.io/oauth2/access_token?code=<code>&client_id=<client_id>&client_secret=<client_secret>&grant_type=authorization_code&redirect_uri=<redirect_uri>`

## Access Token Response

If the authorization code is valid, the API responds with the following payload:

{
"access_token": "uatin87h3m1opd908pa9sdxxxx",
"refresh_token": "rftkljosua2in87h3m1opd90xxxxx",
"token_type": "access_token",
"expires_in": 3600
}

### Response properties

- `access_token`
Short-lived token used to authenticate API requests
- `refresh_token`
Long-lived token used to obtain new access tokens
- `token_type`
Always `access_token`
- `expires_in`
Token expiration time in seconds


Always store access tokens securely and avoid exposing them in client-side applications or public environments.