Table of Contents

Authentication Guide

MediaConvert.io uses Bearer token authentication to secure your API access. This guide covers everything you need to know about managing authentication for your applications.

API Token Management

Creating Your First Token

  1. Sign in to your MediaConvert.io account
  2. Navigate to API Tokens
  3. Click Create New Token
  4. Enter a descriptive name (e.g., Production API, Development, Mobile App)
  5. Set an expiration date (optional but recommended)
  6. Copy the token immediately - it won't be displayed again

Token Security Best Practices

bash 
# ✅ GOOD: Store tokens in environment variables
export MEDIACONVERT_API_TOKEN="mc_live_abc123..."
curl -H "Authorization: Bearer $MEDIACONVERT_API_TOKEN" \
     https://mediaconvert.io/api/v1/me

# ❌ BAD: Never hardcode tokens in source code
curl -H "Authorization: Bearer mc_live_abc123..." \
     https://mediaconvert.io/api/v1/me

Multiple Environments

Create separate tokens for different environments:

bash 
# Development
MEDIACONVERT_DEV_TOKEN="mc_test_dev123..."

# Staging  
MEDIACONVERT_STAGING_TOKEN="mc_test_staging456..."

# Production
MEDIACONVERT_PROD_TOKEN="mc_live_prod789..."

Authentication Implementation

Basic Authentication

All API requests must include the Authorization header:

http 
GET /v1/conversion_jobs HTTP/1.1
Host: api.mediaconvert.io
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Language Examples

Ruby

ruby 
require 'net/http'
require 'json'

class MediaConvertClient
  def initialize(api_token)
    @api_token = api_token
    @base_uri = URI('https://mediaconvert.io/api/v1')
  end

  def create_job(job_params)
    uri = URI.join(@base_uri, 'conversion_jobs')

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(uri)
    request['Authorization'] = "Bearer #{@api_token}"
    request['Content-Type'] = 'application/json'
    request.body = job_params.to_json

    response = http.request(request)
    JSON.parse(response.body)
  end
end

# Usage
client = MediaConvertClient.new(ENV['MEDIACONVERT_API_TOKEN'])
job = client.create_job({
  job_type: 'video',
  input_url: 'https://bucket.s3.amazonaws.com/input.mp4',
  output_url: 'https://bucket.s3.amazonaws.com/output.webm',
  input_format: 'mp4',
  output_format: 'webm'
})

JavaScript/Node.js

javascript 
class MediaConvertAPI {
  constructor(apiToken) {
    this.apiToken = apiToken;
    this.baseURL = 'https://mediaconvert.io/api/v1';
  }

  async createJob(jobData) {
    const response = await fetch(`${this.baseURL}/conversion_jobs`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(jobData)
    });

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

    return response.json();
  }

  async getJob(jobId) {
    const response = await fetch(`${this.baseURL}/conversion_jobs/${jobId}`, {
      headers: {
        'Authorization': `Bearer ${this.apiToken}`
      }
    });

    return response.json();
  }
}

// Usage
const client = new MediaConvertAPI(process.env.MEDIACONVERT_API_TOKEN);

const job = await client.createJob({
  job_type: 'video',
  input_url: 'https://bucket.s3.amazonaws.com/input.mp4',
  output_url: 'https://bucket.s3.amazonaws.com/output.webm',
  input_format: 'mp4',
  output_format: 'webm'
});

Python

python 
import requests
import json
import os

class MediaConvertClient:
    def __init__(self, api_token):
        self.api_token = api_token
        self.base_url = 'https://mediaconvert.io/api/v1'
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_token}',
            'Content-Type': 'application/json'
        })

    def create_job(self, job_data):
        response = self.session.post(
            f'{self.base_url}/conversion_jobs',
            json=job_data
        )
        response.raise_for_status()
        return response.json()

    def get_job(self, job_id):
        response = self.session.get(
            f'{self.base_url}/conversion_jobs/{job_id}'
        )
        response.raise_for_status()
        return response.json()

# Usage
client = MediaConvertClient(os.environ['MEDIACONVERT_API_TOKEN'])

job = client.create_job({
    'job_type': 'video',
    'input_url': 'https://bucket.s3.amazonaws.com/input.mp4',
    'output_url': 'https://bucket.s3.amazonaws.com/output.webm',
    'input_format': 'mp4',
    'output_format': 'webm'
})

Error Handling

Common Authentication Errors

401 Unauthorized - Invalid Token

json 
{
  "error": "unauthorized",
  "message": "Invalid or expired API token"
}

Solutions:
- Check that your token is correct
- Verify the token hasn't expired
- Ensure proper Bearer prefix in Authorization header

401 Unauthorized - Missing Token

json 
{
  "error": "unauthorized", 
  "message": "Authorization header required"
}

Solutions:
- Include Authorization header: Authorization: Bearer YOUR_TOKEN
- Check for typos in header name

403 Forbidden - Insufficient Permissions

json 
{
  "error": "forbidden",
  "message": "Insufficient permissions for this resource"
}

Solutions:
- Check your account tier limits
- Verify the endpoint requires the permissions your token has

Robust Error Handling Example

javascript 
async function makeAuthenticatedRequest(url, options = {}) {
  const defaultHeaders = {
    'Authorization': `Bearer ${process.env.MEDIACONVERT_API_TOKEN}`,
    'Content-Type': 'application/json'
  };

  const response = await fetch(url, {
    ...options,
    headers: { ...defaultHeaders, ...options.headers }
  });

  if (response.status === 401) {
    throw new Error('Authentication failed - check your API token');
  }

  if (response.status === 403) {
    throw new Error('Insufficient permissions');
  }

  if (response.status === 429) {
    const resetTime = response.headers.get('X-RateLimit-Reset');
    throw new Error(`Rate limit exceeded. Resets at ${new Date(resetTime * 1000)}`);
  }

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`API Error: ${errorData.message || response.statusText}`);
  }

  return response.json();
}

Rate Limiting & Authentication

Tokens are subject to rate limiting based on your account tier:

Account Tier Requests/Hour Burst Limit
Free 100 10/minute
Basic 1,000 50/minute
Pro 10,000 200/minute
Enterprise Unlimited 1000/minute

Rate limit headers are returned with every response:

http 
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 956
X-RateLimit-Reset: 1705316400

Security Checklist

  • [ ] Never commit tokens to version control
  • [ ] Use environment variables for token storage
  • [ ] Set expiration dates on tokens when possible
  • [ ] Rotate tokens regularly (every 90 days recommended)
  • [ ] Use different tokens for different environments
  • [ ] Revoke tokens immediately if compromised
  • [ ] Monitor token usage in your account dashboard
  • [ ] Implement proper error handling for auth failures
  • [ ] Use HTTPS only for all API requests

Next Steps