Outlign

Outlign API

v1.0 Documentation

Authentication

The Outlign API uses OAuth2 for secure authentication. This allows users to grant your application access to their data without sharing their credentials.

OAuth2 Flow Overview

Outlign implements the standard OAuth2 authorization code flow. The process involves redirecting users to authenticate with Outlign, then exchanging the authorization code for access tokens.

Authorization Flow Steps

1

Redirect to Authorization URL

Send users to Outlign's authorization endpoint

2

User Grants Permission

User logs in and authorizes your application

3

Exchange Code for Tokens

Your app receives an authorization code and exchanges it for access tokens

4

Make Authenticated Requests

Include the access token in API requests

Step 1: Authorization URL

Direct users to the authorization URL with the required parameters: 

GET https://go.outlign.co/oauth/authorize

Parameters

Parameter Type Description
client_id string Your application's client ID
redirect_uri string URL to redirect to after authorization
response_type string Must be "code"
scope string Requested permissions: "outlign:all"
state string Optional security parameter to prevent CSRF attacks

Step 2: Exchange Code for Access Token

After the user authorizes your application, they'll be redirected to your redirect_uri with an authorization code. Exchange this code for an access token: 

POST https://go.outlign.co/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "def50200c7dd...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 3: Making Authenticated Requests

Include the access token in the Authorization header of your API requests: 

GET https://go.outlign.co/api/v1/companies
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring user re-authentication: 

POST https://go.outlign.co/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&refresh_token=YOUR_REFRESH_TOKEN

Important: Store refresh tokens securely and implement automatic token refresh in your application to maintain uninterrupted API access.

Testing Authentication

Verify your authentication is working by making a request to the user info endpoint: 

GET https://go.outlign.co/api/v1/me

Response

{
  "id": 123,
  "email": "user@example.com",
  "name": "John Doe"
}

Error Handling

Authentication errors return appropriate HTTP status codes and error messages:

401 Unauthorized

{
  "message": "Unauthenticated."
}

403 Forbidden

{
  "message": "This action is unauthorized."
}