API Authentication

Learn how to authenticate your requests to the IriSync API

Overview

The IriSync API uses OAuth 2.0 and API keys for authentication. All API requests must include authentication credentials in the request headers. Unauthenticated requests will be rejected with a 401 Unauthorized response.

There are two authentication methods available:

API Keys
Simple method for server-to-server communication where you control both the client and server
OAuth 2.0
Recommended for third-party applications acting on behalf of IriSync users

Production vs. Development

We recommend using separate API keys for production and development environments to prevent any accidental modifications to production data.

API Key Authentication

API keys provide a simple way to authenticate with the IriSync API. Each API key is associated with your IriSync account and has specific permissions.

Obtaining an API Key

To get an API key:

Log in to your IriSync account
Go to Settings > API Keys
Click "Create New API Key"
Name your key and select the appropriate permissions
Copy your API key (it will only be shown once)

Important Security Notice

Your API key provides access to your IriSync account. Never share it publicly or include it in client-side code. Store it securely and only use it in server-side applications.

Using Your API Key

Include your API key in the Authorization header of your requests as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.irisync.com/api/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

API Key Management Best Practices

Rotate keys regularly
Create new API keys and deprecate old ones on a schedule
Use environment variables
Never hardcode API keys in your application code
Limit permissions
Grant only the permissions each key needs
Monitor usage
Regularly check API key usage in your IriSync dashboard

OAuth 2.0 Authentication

OAuth 2.0 is the recommended authentication method for third-party applications that need to access IriSync on behalf of users without storing their credentials.

Setting Up OAuth

To use OAuth with IriSync:

Register your application in the IriSync Developer Portal
Obtain your Client ID and Client Secret
Configure your redirect URIs

Redirect URIs

Your redirect URI must exactly match what you registered in the Developer Portal. We recommend using HTTPS for all redirect URIs in production.

OAuth 2.0 Flow

IriSync supports the standard OAuth 2.0 Authorization Code flow:

1. Redirect to Authorization URL

Redirect the user to the IriSync authorization URL:

https://api.irisync.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=read,write

2. Handle the Callback

After the user authorizes your application, IriSync will redirect to your redirect URI with an authorization code:

https://your-app.com/callback?code=AUTHORIZATION_CODE

3. Exchange Code for Access Token

Exchange the authorization code for an access token:

POST https://api.irisync.com/oauth/token Content-Type: application/json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "code": "AUTHORIZATION_CODE", "grant_type": "authorization_code", "redirect_uri": "YOUR_REDIRECT_URI" }

4. Use Access Token in API Requests

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

Authorization: Bearer ACCESS_TOKEN

Refreshing Access Tokens

Access tokens expire after a certain period (usually 1 hour). Use the refresh token to obtain a new access token:

// When token expires, use refresh token to get a new one
const refreshAccessToken = async (refreshToken) => {
  const response = await fetch('https://api.irisync.com/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      refresh_token: refreshToken,
      grant_type: 'refresh_token'
    })
  });
  
  const { access_token, refresh_token, expires_in } = await response.json();
  // Store the new tokens
};

Available Scopes

Scopes define the level of access your application has to a user's IriSync account:

read
Read-only access to user data
write
Modify user data
content:read
Access content data only
content:write
Create and modify content
analytics:read
Access analytics data

Best Practice

Always request the minimal set of scopes needed for your application.

Next Steps

Now that you understand authentication, check out these resources:

API Endpoints Reference API Reference Platform Integration

// When token expires, use refresh token to get a new one const refreshAccessToken = async (refreshToken) => { const response = await fetch('https://api.irisync.com/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', refresh_token: refreshToken, grant_type: 'refresh_token' }) }); const { access_token, refresh_token, expires_in } = await response.json(); // Store the new tokens };