YeboLink Documentation

Appearance

Authentication ​

YeboLink uses two types of authentication depending on your use case:

  1. JWT Tokens: For dashboard access and account management
  2. API Keys: For programmatic message sending and API access

JWT Authentication ​

JWT (JSON Web Token) authentication is used for accessing dashboard features, managing your account, creating API keys, and purchasing credits.

How It Works ​

  1. Sign up or log in to receive a JWT token
  2. Include the token in the Authorization header as a Bearer token
  3. Token expires after 30 days

Getting a JWT Token ​

Signup ​

Create a new account:

bash
curl -X POST https://api.yebolink.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "SecurePassword123!",
    "company_name": "My Company",
    "phone": "+1234567890",
    "country": "US"
  }'
javascript
const response = await fetch('https://api.yebolink.com/api/v1/auth/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'you@example.com',
    password: 'SecurePassword123!',
    company_name: 'My Company',
    phone: '+1234567890',
    country: 'US'
  })
});

const data = await response.json();
python
import requests

response = requests.post(
    'https://api.yebolink.com/api/v1/auth/signup',
    json={
        'email': 'you@example.com',
        'password': 'SecurePassword123!',
        'company_name': 'My Company',
        'phone': '+1234567890',
        'country': 'US'
    }
)

data = response.json()

Response:

json
{
  "success": true,
  "data": {
    "workspace": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Company",
      "email": "you@example.com",
      "email_verified": false,
      "credits_balance": 10
    },
    "message": "Verification email sent to you@example.com"
  }
}

Login ​

Exchange your credentials for a JWT token:

bash
curl -X POST https://api.yebolink.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "SecurePassword123!"
  }'
javascript
const response = await fetch('https://api.yebolink.com/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'you@example.com',
    password: 'SecurePassword123!'
  })
});

const { data } = await response.json();
const token = data.token;

// Store token for subsequent requests
localStorage.setItem('jwt_token', token);
python
import requests

response = requests.post(
    'https://api.yebolink.com/api/v1/auth/login',
    json={
        'email': 'you@example.com',
        'password': 'SecurePassword123!'
    }
)

data = response.json()
token = data['data']['token']

# Store token for subsequent requests
php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.yebolink.com/api/v1/auth/login',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => 'you@example.com',
        'password' => 'SecurePassword123!'
    ])
]);

$response = curl_exec($curl);
$data = json_decode($response, true);
$token = $data['data']['token'];

curl_close($curl);
?>

Response:

json
{
  "success": true,
  "data": {
    "workspace": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Company",
      "email": "you@example.com",
      "email_verified": true,
      "credits_balance": 10
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3b3Jrc3BhY2VJZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsImlhdCI6MTYzMjM0NTY3OCwiZXhwIjoxNjM0OTM3Njc4fQ.abc123def456"
  }
}

Using JWT Token ​

Include the JWT token in the Authorization header:

bash
curl https://api.yebolink.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
javascript
const token = localStorage.getItem('jwt_token');

const response = await fetch('https://api.yebolink.com/api/v1/api-keys', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
python
token = "your_jwt_token"

response = requests.get(
    'https://api.yebolink.com/api/v1/api-keys',
    headers={
        'Authorization': f'Bearer {token}'
    }
)
php
<?php
$token = "your_jwt_token";

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.yebolink.com/api/v1/api-keys',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token"
    ]
]);

$response = curl_exec($curl);
?>

JWT Protected Endpoints ​

The following endpoints require JWT authentication:

  • POST /api/v1/api-keys - Create API key
  • GET /api/v1/api-keys - List API keys
  • DELETE /api/v1/api-keys/:id - Delete API key
  • POST /api/v1/webhooks - Create webhook
  • GET /api/v1/webhooks - List webhooks
  • PUT /api/v1/webhooks/:id - Update webhook
  • DELETE /api/v1/webhooks/:id - Delete webhook
  • POST /api/v1/billing/checkout - Create checkout session
  • GET /api/v1/billing/transactions - List transactions
  • GET /api/v1/contacts - List contacts
  • POST /api/v1/contacts - Create contact

API Key Authentication ​

API Keys are used for sending messages and accessing the messaging API programmatically. They're ideal for:

  • Backend services
  • Automated messaging
  • Server-to-server communication
  • Production applications

Creating an API Key ​

You need a JWT token to create an API key:

bash
curl -X POST https://api.yebolink.com/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Production API Key",
    "scopes": ["send_messages", "read_messages"]
  }'
javascript
const token = localStorage.getItem('jwt_token');

const response = await fetch('https://api.yebolink.com/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    name: 'Production API Key',
    scopes: ['send_messages', 'read_messages']
  })
});

const data = await response.json();
const apiKey = data.data.key;

// IMPORTANT: Save this key - it's only shown once!
console.log('API Key:', apiKey);
python
import requests

token = "your_jwt_token"

response = requests.post(
    'https://api.yebolink.com/api/v1/api-keys',
    headers={
        'Authorization': f'Bearer {token}'
    },
    json={
        'name': 'Production API Key',
        'scopes': ['send_messages', 'read_messages']
    }
)

data = response.json()
api_key = data['data']['key']

# IMPORTANT: Save this key - it's only shown once!
print(f'API Key: {api_key}')
php
<?php
$token = "your_jwt_token";

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.yebolink.com/api/v1/api-keys',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "Authorization: Bearer $token"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Production API Key',
        'scopes' => ['send_messages', 'read_messages']
    ])
]);

$response = curl_exec($curl);
$data = json_decode($response, true);
$apiKey = $data['data']['key'];

// IMPORTANT: Save this key - it's only shown once!
curl_close($curl);
?>

Response:

json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Production API Key",
    "key": "ybk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
    "key_prefix": "ybk_live_ab...",
    "scopes": ["send_messages", "read_messages"],
    "created_at": "2025-11-02T12:00:00Z",
    "warning": "Save this key securely. It will not be shown again."
  }
}

Save Your API Key

The full API key is only shown once during creation. Store it securely in your environment variables or secrets manager. You won't be able to retrieve it again!

API Key Scopes ​

Available scopes:

  • send_messages: Send messages via API
  • read_messages: Retrieve message details and history
  • manage_contacts: Create, update, delete contacts
  • manage_webhooks: Create, update webhooks (usually not needed for API keys)

Using API Keys ​

Include your API key in the X-API-Key header:

bash
curl -X POST https://api.yebolink.com/api/v1/messages/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ybk_live_your_api_key" \
  -d '{
    "to": "+1234567890",
    "channel": "sms",
    "content": {
      "text": "Hello from YeboLink!"
    }
  }'
javascript
const API_KEY = process.env.YEBOLINK_API_KEY;

const response = await fetch('https://api.yebolink.com/api/v1/messages/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY
  },
  body: JSON.stringify({
    to: '+1234567890',
    channel: 'sms',
    content: {
      text: 'Hello from YeboLink!'
    }
  })
});

const data = await response.json();
python
import os
import requests

API_KEY = os.environ.get('YEBOLINK_API_KEY')

response = requests.post(
    'https://api.yebolink.com/api/v1/messages/send',
    headers={
        'X-API-Key': API_KEY
    },
    json={
        'to': '+1234567890',
        'channel': 'sms',
        'content': {
            'text': 'Hello from YeboLink!'
        }
    }
)
php
<?php
$apiKey = getenv('YEBOLINK_API_KEY');

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.yebolink.com/api/v1/messages/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "X-API-Key: $apiKey"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '+1234567890',
        'channel' => 'sms',
        'content' => [
            'text' => 'Hello from YeboLink!'
        ]
    ])
]);

$response = curl_exec($curl);
?>
ruby
require 'net/http'
require 'json'
require 'uri'

API_KEY = ENV['YEBOLINK_API_KEY']

uri = URI('https://api.yebolink.com/api/v1/messages/send')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = API_KEY
request.body = {
  to: '+1234567890',
  channel: 'sms',
  content: {
    text: 'Hello from YeboLink!'
  }
}.to_json

response = http.request(request)
go
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("YEBOLINK_API_KEY")
    url := "https://api.yebolink.com/api/v1/messages/send"

    payload := map[string]interface{}{
        "to": "+1234567890",
        "channel": "sms",
        "content": map[string]string{
            "text": "Hello from YeboLink!",
        },
    }

    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

API Key Protected Endpoints ​

The following endpoints require API key authentication:

  • POST /api/v1/messages/send - Send single message
  • POST /api/v1/messages/bulk - Send bulk messages
  • GET /api/v1/messages - List messages
  • GET /api/v1/messages/:id - Get message details

Security Best Practices ​

Storing Credentials ​

Environment Variables

Always store API keys and JWT tokens in environment variables, never hardcode them in your source code.

Node.js (.env file):

bash
YEBOLINK_API_KEY=ybk_live_your_api_key
YEBOLINK_JWT_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Python (.env file):

bash
YEBOLINK_API_KEY=ybk_live_your_api_key
YEBOLINK_JWT_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

PHP:

php
// Use environment variables or .env files with libraries like vlucas/phpdotenv
$apiKey = getenv('YEBOLINK_API_KEY');

Key Rotation ​

Regularly rotate your API keys, especially if:

  • A key has been exposed
  • An employee with key access leaves
  • You suspect unauthorized access
  • As part of regular security hygiene (every 90 days)

To rotate a key:

  1. Create a new API key
  2. Update your application to use the new key
  3. Test that everything works
  4. Delete the old API key

Revoking API Keys ​

If an API key is compromised, immediately delete it:

bash
curl -X DELETE https://api.yebolink.com/api/v1/api-keys/YOUR_KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Rate Limiting ​

API keys are subject to rate limiting:

  • General API: 100 requests per minute
  • Bulk Send: 10 requests per 5 minutes
  • Auth Routes: 5 attempts per 15 minutes

See Rate Limits for more details.

Password Management ​

Forgot Password ​

Request a password reset:

bash
curl -X POST https://api.yebolink.com/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com"
  }'
javascript
const response = await fetch('https://api.yebolink.com/api/v1/auth/forgot-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'you@example.com'
  })
});

Reset Password ​

Use the token from the reset email:

bash
curl -X POST https://api.yebolink.com/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "password": "NewSecurePassword123!"
  }'
javascript
const response = await fetch('https://api.yebolink.com/api/v1/auth/reset-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token: 'reset_token_from_email',
    password: 'NewSecurePassword123!'
  })
});

Error Responses ​

Invalid API Key ​

json
{
  "success": false,
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Expired JWT Token ​

json
{
  "success": false,
  "error": "token_expired",
  "message": "Your session has expired. Please login again."
}

Insufficient Permissions ​

json
{
  "success": false,
  "error": "forbidden",
  "message": "This API key doesn't have permission to perform this action"
}

Testing Authentication ​

Use our test endpoint to verify your authentication:

bash
# Test API Key
curl https://api.yebolink.com/api/v1/messages \
  -H "X-API-Key: ybk_live_your_api_key"

# Test JWT Token
curl https://api.yebolink.com/api/v1/api-keys \
  -H "Authorization: Bearer your_jwt_token"

Next Steps ​

Built with VitePress

Copyright © 2025 YeboLink