SSO Integration Documentation

Complete guide to integrating Vettly SSO into your application

Overview

Vettly SSO (Single Sign-On) allows external applications to verify candidate identities through a secure API. This is commonly used by resume builders and other platforms that need to authenticate users from Vettly.

Free Tier Available

Start with 30 requests per day. Upgrade to higher tiers as your usage grows.

Quick Start

Register Your Application

Company name
Contact email
Website (optional)
Allowed callback URLs (optional)

Save Your API Key

After registration, you'll receive an API key. Save it securely - it will only be shown once.

Never commit API keys to version control. Store them in environment variables or secure configuration.

Integrate the API

Use your API key to authenticate requests to the SSO verification endpoint. See code examples below.

Authentication

All API requests must include your API key. You can use either method below, or send both headers together for maximum compatibility:

Method 1: Authorization Header (Recommended)

Authorization: Bearer vettly_sk_live_your_api_key_here

Method 2: X-API-Key Header (Alternative/Fallback)

X-API-Key: vettly_sk_live_your_api_key_here

Tip: For maximum compatibility, you can send both headers together. The API will accept either one, so sending both ensures your request works regardless of which header format is preferred.

API Endpoint

Verify Candidate

Verify a candidate using their SSO code and secret. This endpoint returns candidate information formatted for your application.

Endpoint

GET https://api.vettly.ai/api/v1/sso/verify-candidate

Query Parameters

sso_code*

SSO code generated during candidate registration/login

sso_secret*

SSO user secret provided during candidate registration/login

Required Headers

Authorization*

Bearer token with your API key (e.g., "Bearer vettly_sk_live_...")

Alternative/Fallback: Use X-API-Key header instead, or send both headers together for maximum compatibility

Response

{
  "success": true,
  "message": "Candidate verified successfully",
  "data": {
    "id": "uuid",
    "email": "candidate@example.com",
    "name": "John Doe",
    "jobTitle": "Software Engineer",
    "isVerified": true,
    "isActive": true,
    "emailVerifiedAt": "2024-01-01T00:00:00Z",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "profile": {
      "phoneNumber": "+1234567890",
      "location": "New York, NY",
      "skills": ["JavaScript", "TypeScript"],
      "experience": 5,
      "resumeUrl": "https://...",
      "portfolioUrl": "https://...",
      "linkedinUrl": "https://...",
      "bio": "Experienced software engineer...",
      "profilePicture": "https://..."
    }
  }
}

Code Examples

JavaScript / Node.js

const axios = require('axios');

async function verifyCandidate(ssoCode, ssoSecret) {
  try {
    const response = await axios.get('https://api.vettly.ai/api/v1/sso/verify-candidate', {
      params: {
        sso_code: ssoCode,
        sso_secret: ssoSecret
      },
      headers: {
        'Authorization': `Bearer ${process.env.VETTLY_API_KEY}`,
        'X-API-Key': process.env.VETTLY_API_KEY, // Fallback for maximum compatibility
      }
    });
    
    return response.data.data;
  } catch (error) {
    if (error.response?.status === 401) {
      throw new Error('Invalid API key');
    }
    if (error.response?.status === 429) {
      throw new Error('Rate limit exceeded');
    }
    throw error;
  }
}

// Usage
const candidate = await verifyCandidate('sso_code_here', 'sso_secret_here');
console.log(candidate.email, candidate.name);

Python

import requests
import os

def verify_candidate(sso_code, sso_secret):
    api_key = os.getenv('VETTLY_API_KEY')
    url = 'https://api.vettly.ai/api/v1/sso/verify-candidate'
    
    params = {
        'sso_code': sso_code,
        'sso_secret': sso_secret
    }
    
    headers = {
        'Authorization': f'Bearer {api_key}',
        'X-API-Key': api_key,  # Fallback for maximum compatibility
    }
    
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    
    return response.json()['data']

# Usage
candidate = verify_candidate('sso_code_here', 'sso_secret_here')
print(candidate['email'], candidate['name'])

cURL

curl -X GET "https://api.vettly.ai/api/v1/sso/verify-candidate?sso_code=CODE&sso_secret=SECRET" \
  -H "Authorization: Bearer vettly_sk_live_your_api_key_here" \
  -H "X-API-Key: vettly_sk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Rate Limiting

All API requests are subject to rate limiting based on your tier:

FREE

requests per day

STARTER

100

requests per day

PRO

1,000

requests per day

ENTERPRISE

1M+

requests per day

Rate limits reset daily at midnight UTC. When you exceed your limit, you'll receive a 429 status code with rate limit information in response headers.

Error Handling

401 Unauthorized

Invalid or missing API key

{
  "success": false,
  "message": "API key required. Provide it in Authorization: Bearer <key> or X-API-Key header",
  "error": {
    "code": "AUTHENTICATION_ERROR"
  }
}

429 Too Many Requests

Rate limit exceeded

{
  "success": false,
  "message": "Rate limit exceeded. You have used all 30 requests for today.",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED"
  }
}

// Response headers include:
// X-RateLimit-Limit: 30
// X-RateLimit-Remaining: 0
// X-RateLimit-Reset: 86400
// Retry-After: 86400

400 Bad Request

Invalid parameters

{
  "success": false,
  "message": "Both sso_code and sso_secret query parameters are required",
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

Best Practices

Store API keys securely
Never commit API keys to version control. Use environment variables or secure configuration management.
Handle rate limits gracefully
Implement exponential backoff and respect the Retry-After header when rate limited.
Validate callback URLs
Only register callback URLs that you control to prevent open redirect vulnerabilities.
Monitor usage
Use the self-service dashboard to monitor your API usage and upgrade your tier when needed.

Support & Resources

Get your API key

Access Dashboard

Manage your integration