OAuth 2.0 Authorization Guide

This guide explains how to implement OAuth 2.0 authentication with the Matik API, including the producer and consumer roles.

Postman users can download this prefilled OAuth collection. Just enter your Client ID and secret.

Understanding Matik's OAuth Roles

Matik's API uses two distinct roles for OAuth authentication:

1. Producer Role: Used for creating and managing templates, data sources, and other resources
2. Consumer Role: Used for generating presentations from existing templates without access to data sources.

Prerequisites

Before implementing OAuth 2.0 with Matik, you'll need:

1. A Matik account with API access
2. Client credentials (client ID and client secret) with producer and consumer scopes.
3. Basic understanding of OAuth 2.0 flow

Producer Role Authentication

The producer role has broader permissions and is used for administrative tasks.

Obtaining a Producer Token

1. Direct user to the following url with a redirect_uri you control.

const authUrl = 'https://app.matik.io/oauth/authorize' + 
  '?response_type=code' +
  '&client_id=YOUR_CLIENT_ID' +
  '&redirect_uri=YOUR_REDIRECT_URI' +
  '&scope=producer+consumer' +
  '&state=OPTIONAL_STATE_VALUE';

2. Use the code you receive to fetch access and refresh tokens.

async function getToken(code, clientId, clientSecret, redirectUri) {
  try {
    const response = await fetch('https://app.matik.io/api/v1/oauth/token/', {
      method: 'POST',
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        client_id: clientId,
        client_secret: clientSecret,
        redirect_uri: redirectUri,
        code: code,
        scope: 'producer consumer'
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error obtaining producer token:', error);
    throw error;
  }
}

3. Use the access_token to make a request.

async function createTemplate(name, accessToken) {
  try {
    const response = await fetch('https://app.matik.io/api/1.0/templates/powerpoint', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: name })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Error creating template:', error);
    throw error;
  }
}

Consumer Role Authentication

The consumer scope has limited permissions focused on generating presentations.

Using the Consumer Token

async function generatePresentation(templateId, inputs, consumerToken) {
  try {
    const response = await fetch('https://app.matik.io/api/1.0/presentations/', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${consumerToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        template_id: templateId,
        inputs: inputs,
        name: "Consumer Generated Presentation"
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Error generating presentation:', error);
    throw error;
  }
}

Token Lifecycle Management

OAuth tokens have a limited lifespan. You'll need to refresh the token if it expires.

async function refreshToken(clientId, clientSecret, refreshToken, scope) {
  try {
    const response = await fetch('https://app.matik.io/api/v1/oauth/token/', {
      method: 'POST',
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        client_id: clientId,
        client_secret: clientSecret,
        scope: scope,
        refresh_token: refreshToken
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data.access_token;
  } catch (error) {
    console.error('Error refreshing token:', error);
    throw error;
  }
}

Best Practices

1. Store credentials securely: Never expose client secrets in client-side code
2. Use appropriate roles: Use the producer role only when necessary
3. Implement token caching: Avoid requesting new tokens for every API call
4. Handle token expiration: Refresh tokens before they expire
5. Implement error handling: Handle authentication errors gracefully

Troubleshooting

Common authentication issues and solutions:

Issue	Solution
Invalid client credentials	Double-check your client ID and secret
Token expired	Implement automatic token refresh
Insufficient permissions	Verify you're using the correct role (producer/consumer)
Rate limiting	Implement exponential backoff for retries

Next Steps

Now that you understand OAuth authentication with Matik:

1. Explore the API Reference for detailed endpoint documentation
2. Check out our Quick Start Guide for a complete implementation example
3. Learn about Data Sources to connect your data

For any questions or issues with authentication, please contact our support team at support@matik.io.