API Authentication

This guide explains the authentication methods supported by the Sharmo API and how to implement them securely in your applications.

Introduction

The Sharmo API uses secure authentication methods to ensure that only authorized applications and users can access the API. We currently support three authentication methods:

API Keys

API keys provide a simple way to authenticate requests to the Sharmo API without involving end-users.

When to Use API Keys

Getting an API Key

  1. Log in to the Sharmo Developer Portal
  2. Navigate to "Applications" and select your application
  3. Go to the "API Keys" tab
  4. Click "Generate New API Key"
  5. Store the API key securely (it will only be shown once)

Using API Keys

Include your API key in the Authorization header of your HTTP requests:

API Key Example 
curl -X GET "https://api.sharmo.io/v1/properties" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"
JavaScript Example 
const fetchProperties = async () => {
  const response = await fetch('https://api.sharmo.io/v1/properties', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });
  
  const data = await response.json();
  return data;
};

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization that enables third-party applications to obtain limited access to a user's account.

When to Use OAuth

OAuth Flow

Sharmo supports the following OAuth 2.0 flows:

Implementing Authorization Code Flow

  1. Register your application in the Developer Portal
  2. Redirect the user to the Sharmo authorization endpoint
  3. Sharmo redirects back to your application with an authorization code
  4. Exchange the authorization code for an access token
  5. Use the access token to authenticate API requests
Step 1: Redirect to Authorization Endpoint 
const clientId = 'YOUR_CLIENT_ID';
const redirectUri = 'https://yourapp.com/callback';
const scope = 'read:properties write:transactions';

const authUrl = `https://auth.sharmo.io/authorize?client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code&scope=${encodeURIComponent(scope)}`;

// Redirect the user
window.location.href = authUrl;
Step 2: Exchange Code for Token 
const exchangeCodeForToken = async (code) => {
  const response = await fetch('https://auth.sharmo.io/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      code: code,
      redirect_uri: 'https://yourapp.com/callback'
    })
  });
  
  const tokens = await response.json();
  
  // Store tokens securely
  localStorage.setItem('access_token', tokens.access_token);
  localStorage.setItem('refresh_token', tokens.refresh_token);
  
  return tokens;
};
Step 3: Use Access Token 
const getUserProfile = async () => {
  const accessToken = localStorage.getItem('access_token');
  
  const response = await fetch('https://api.sharmo.io/v1/user/profile', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  });
  
  return response.json();
};

Token Refresh

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

Refreshing Access Tokens 
const refreshAccessToken = async () => {
  const refreshToken = localStorage.getItem('refresh_token');
  
  const response = await fetch('https://auth.sharmo.io/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      refresh_token: refreshToken
    })
  });
  
  const tokens = await response.json();
  
  localStorage.setItem('access_token', tokens.access_token);
  // Note: Sometimes a new refresh token is issued as well
  if (tokens.refresh_token) {
    localStorage.setItem('refresh_token', tokens.refresh_token);
  }
  
  return tokens;
};

JWT Authentication

JSON Web Tokens (JWT) are an open standard that defines a compact and self-contained way for securely transmitting information as a JSON object.

When to Use JWT

JWT Structure

JWTs consist of three parts separated by dots:

  1. Header - Contains the token type and signing algorithm
  2. Payload - Contains the claims (user info, permissions, etc.)
  3. Signature - Verifies the token hasn't been altered

Using JWT with Sharmo API

JWT Example 
// JWT tokens are typically obtained after authentication
// with the Sharmo auth service

const makeAuthenticatedRequest = async () => {
  const jwt = localStorage.getItem('jwt_token');
  
  const response = await fetch('https://api.sharmo.io/v1/protected-resource', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${jwt}`,
      'Content-Type': 'application/json'
    }
  });
  
  return response.json();
};

Security Best Practices

API Key Security

OAuth Security

JWT Security

General Security Practices

Introduction Integration Guide