# OAuth Authentication

The Tradier API uses OAuth 2.0 for authentication and authorization. We support the Authorization Code flow (server-side application), which provides secure access to trading accounts and market data. For an individual developer working on applications and algorithms for their use, OAuth is not necessary; all API calls can be made with your API Token (or Sandbox Token) found in your [API Settings](https://dash.tradier.com/settings/api). If you are working on an application for public release please reach out to our team at <sales@tradier.com> about becoming a Tradier partner.

## Overview

OAuth 2.0 is a straightforward protocol that allows developers to integrate with Tradier's endpoints using standard client libraries. Once you are accepted as a Tradier partner, you will be invited to our partner developer portal, where you can register and maintain an application with us. The authentication process involves:

1. **Register your application** with Tradier to get your clientID and clientSecret
2. **Redirect users** to our authorization URL, where they will approve scopes for your application
3. **Parse the authorization code** from the callback
4. **Exchange the authorization code** for an access token
5. **Use the access token** to make API requests

## Token Types and Lifespans

### Authorization Codes

* **Lifespan**: 10 minutes
* **Purpose**: Short-lived codes are provided after user authorization
* **Usage**: Exchanged for access tokens

### Access Tokens (Bearer Tokens)

* **Lifespan**: 24 hours
* **Purpose**: Used to authenticate API requests
* **Usage**: Include in the `Authorization` header as `Bearer {token}`
* **Renewal**: Must exchange a new authorization code when expired

### Refresh Tokens

* **Lifespan**: Do not expire
* **Purpose**: Generate new access tokens without user re-authorization
* **Availability**: Only available to approved Tradier Partners
* **Approval**: Contact <techsupport@tradier.com> to request access

> <br />

## Authentication Flow

### Step 1: Get Authorization Code

**Required Parameters:**

* `client_id`: Your application's client ID
* `scope`: Requested permissions (e.g., `read`, `trade`)
* `state`: Random string for security validation

**Scopes**

Scopes control the level of access granted to your application:

* **`read`**: Read access to account information, positions, and market data
* **`write`**: Write access to account data (does not include placing or updating trades)
* **`market`**: Access market data (does not include streaming)
* **`trade`**: Permission to place and manage trades
* **`stream`**: Access to real-time streaming data

Users will be prompted to approve the requested scopes during authorization.

**Example Authorization URL:**

```
https://api.tradier.com/v1/oauth/authorize?client_id={clientId}&scope={scopes}&state={state}
```

**Response**

Since this call should be made in a browser, a successful response will be a 302 redirect to Tradier Brokerage’s website where the user can log in and authorize.

### Step 2: Handle Callback

If the user authorizes your application, a call will be made to the callback URL registered with your application. That callback will look something like:

```
http://your-callback-url.com?code={authorization_code}&state={state}
```

<br />

**code** - Your authorization code\
**state** - The same unique string you sent in the request above

*Note: The reason the state is sent back to you is to make sure no-one is tampering with this exchange. If it’s different than the original you should abort the exchange and start over*

If everything checks out, you’ve got an authorization code you can exchange for an access token (Congrats!). This code expires in 10-minutes so be sure to move on to the next step efficiently.

<br />

### Step 3: Exchange Code for Access Token

Make a POST request to exchange the authorization code:

```
POST https://api.tradier.com/v1/oauth/accesstoken
```

**Authentication**: HTTP Basic Authentication

* Your client ID
* Your client secret

*You will need to base64 encode your clientID and clientSecret as clientID:clientSecret*

**Headers:**

```
Authorization: Basic {base64_encoded_credentials}
Content-Type: application/x-www-form-urlencoded
Accept: application/json
```

**Body Parameters:**

* `grant_type`: Set to `authorization_code`
* `code`: The authorization code from Step 2

**Example Request:**

```bash
curl -X POST https://api.tradier.com/v1/oauth/accesstoken \
  -H "Authorization: Basic {base64_credentials}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code={auth_code}"
```

### Step 4: Use Access Token

Include the access token in API requests:

```
Authorization: Bearer {access_token}
```

**Example API Request:**

```bash
curl -X GET "https://api.tradier.com/v1/user/profile" \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Accept: application/json'
```

## Refresh Token Flow (Partners Only)

If you have refresh token access, you can obtain new access tokens without user re-authorization:

```
POST https://api.tradier.com/v1/oauth/refreshtoken
```

**Authentication**: HTTP Basic Authentication (same as access token exchange)

**Body Parameters:**

* `grant_type`: Set to `refresh_token`
* `refresh_token`: Your refresh token

<br />

## Security Best Practices

1. **Protect Access Tokens**: Treat access tokens like passwords - never expose them in client-side code
2. **Validate State Parameters**: Always verify the state parameter to prevent CSRF attacks
3. **Use HTTPS**: All OAuth exchanges must use secure connections
4. **Store Secrets Securely**: Keep client secrets in secure server-side storage
5. **Monitor Token Expiration**: Implement proper token refresh logic

<br />

<br />

## Support

For technical questions or to request refresh token access:

* **Email**: <techsupport@tradier.com>
* **Partners**: Access OAuth credentials through your organization's dashboard