Documentation

Introduction

Authink provides a simple, powerful API for sending OTPs and magic links. Get started in under 5 minutes with our REST API or SDK.

Quick Start Guide Email OTP API Keys Security Best Practices

Authink is a modern authentication infrastructure designed for developers who want to add secure, passwordless authentication to their applications without managing complex infrastructure.

Sub-50ms Latency

Our globally distributed infrastructure ensures your users receive codes instantly.

99.99% Uptime SLA

Enterprise-grade reliability with redundant data centers worldwide.

End-to-End Encryption

All data encrypted at rest and in transit using AES-256 and TLS 1.3.

GDPR & SOC 2 Compliant

Built with privacy and security standards from day one.

New here? We recommend starting with our Quick Start guide below, or jump straight to Email OTP if you're ready to integrate.

1

Quick Start

Get up and running with Authink in three simple steps. This guide will walk you through sending your first OTP in under 5 minutes.

Create an Account & Get Your API Key

Sign up for a free account at app.authink.app. Once logged in, navigate to Settings → API Keys and create your first key. Keep this secret — you'll need it for every API call.

terminal

# Sign up and get your free API key at:
→ https://app.authink.app/register

# Your API key looks like this:
sk_live_a1b2c3d4e5f6g7h8i9j0...

Install the SDK

Add Authink to your project using your preferred package manager. We support Node.js 16+, Python 3.8+, Go 1.19+, Ruby 3.0+, and more.

terminal

npm install @authink/sdk

terminal

yarn add @authink/sdk

terminal

pnpm add @authink/sdk

Send Your First OTP

Initialize the client with your API key and send an OTP to any email address. That's it — you've just sent your first authentication code!

auth.ts

import { Authink } from '@authink/sdk';

const authink = new Authink('sk_live_...');

// Send an OTP to user's email
await authink.sendOTP({
  email: 'user@example.com',
  expiresIn: 300 // 5 minutes
});

// ✅ OTP delivered successfully!

You're all set! Check out the Email OTP guide next to learn about verification, error handling, and customization options.

2

Installation

Authink provides official SDKs for major programming languages. Choose your preferred method below.

Package Managers

NPM

npm install @authink/sdk

Node.js 16+ / TypeScript

YARN

yarn add @authink/sdk

Alternative package manager

PNPM

pnpm add @authink/sdk

Fast, disk space efficient

Other Languages

Language	Command	Version
Python	`pip install authink-sdk`	3.8+
Go	`go get github.com/authink/authink-go`	1.19+
Ruby	`gem install authink`	3.0+
PHP	`composer require authink/sdk`	8.1+

Note: Always pin your dependency versions in production to avoid unexpected breaking changes. We follow semantic versioning.

3

Email OTP Authentication

Email One-Time Passwords (OTP) are the most common form of passwordless authentication. Users receive a numeric code via email and enter it to verify their identity.

How It Works

Your application calls the Send OTP endpoint with the user's email
Authink generates a random code and sends it via email
User enters the code in your application
Your application calls Verify OTP to validate the code
If valid, Authink returns a session token for the authenticated user

Sending an OTP

send-otp.ts

import { Authink } from '@authink/sdk';

const authink = new Authink('sk_live_...');

try {
  const result = await authink.sendOTP({
    email: 'user@example.com',
    expiresIn: 300,        // Optional: expiry in seconds (default: 300)
    length: 6,            // Optional: code length (default: 6)
    subject: 'Your verification code', // Optional: email subject
    metadata: {           // Optional: custom metadata
      userId: 'usr_12345',
      ipAddress: '192.168.1.1'
    }
  });
  
  console.log('OTP sent successfully!', result);
} catch (error) {
  console.error('Failed to send OTP:', error.message);
}

Request Parameters

Parameter	Type	Required	Description
email	string	Yes	The recipient's email address. Must be a valid email format.
expiresIn	number	No	Time in seconds before the OTP expires. Range: 60-900. Default: 300 (5 min).
length	number	No	Number of digits in the OTP. Options: 4, 6, 8. Default: 6.
subject	string	No	Custom subject line for the email. Default: "Your verification code".
metadata	object	No	Arbitrary key-value pairs stored with the OTP for later retrieval.

Rate Limits: You can send a maximum of 10 OTPs per email per minute and 50 per hour per email address to prevent abuse.

4

Verify an OTP

After the user enters the code they received, verify it against the original OTP request. On successful verification, you'll receive a session token that can be used to authenticate subsequent requests.

verify.ts

const result = await authink.verifyOTP({
  email: 'user@example.com',
  code: '847291'
});

if (result.success) {
  // Store session token securely
  const { token, expiresAt, user } = result.session;
  
  console.log('User authenticated:', user.id);
  console.log('Session expires:', new Date(expiresAt).toISOString());
} else {
  // Handle invalid or expired code
  console.error('Verification failed:', result.error);
}

Response Object

Field	Type	Description
success	boolean	Whether verification was successful
session.token	string	JWT token for authenticated sessions
session.expiresAt	ISO string	When the session token expires
session.user.id	string	Unique identifier for the user
error.code	string	Error code if verification failed (e.g., "expired", "invalid", "max_attempts")

5

Magic Links

Magic links provide a completely frictionless authentication experience. Users click a link in their email and are instantly authenticated — no code entry required.

magic-link.ts

const magicLinkResult = await authink.sendMagicLink({
  email: 'user@example.com',
  redirectUrl: 'https://your-app.com/auth/callback',
  expiresIn: 900, // 15 minutes
  generateQrCode: false
});

// The magic link is sent automatically to the user's email
// When clicked, they'll be redirected to your callback URL
// with a `token` query parameter

Security Note: Always validate the redirect URL against an allowlist of authorized domains to prevent open redirect attacks.

6

Session Management

After successful authentication, Authink issues a session token (JWT) that can be used to identify the user in subsequent requests. Sessions can be validated, refreshed, and revoked as needed.

sessions.ts

// Validate an existing session token
const session = await authink.verifySession(token);
// Returns: { valid: true, user: {...}, expiresAt: '...' }

// Revoke a specific session (logout)
await authink.revokeSession(sessionId);

// Revoke all sessions for a user
await authink.revokeAllSessions(userId);

7

API Keys

API keys are used to authenticate your requests to the Authink API. Each key has specific scopes that determine what actions it can perform.

keys.ts

// List all API keys for your account
const keys = await authink.listAPIKeys();
// Returns array of key objects with name, prefix, status, created_at

// Create a new API key with scoped permissions
const newKey = await authink.createAPIKey({
  name: 'Production Server',
  scopes: ['otp:send', 'otp:verify', 'sessions:read'],
  expiresAt: null, // or ISO date string for temporary keys
  ipWhitelist: ['192.168.1.0/24'] // Optional IP restriction
});

console.log('New key created:', newKey.key);
// ⚠️ Store this key securely - you won't see it again!

// Revoke a compromised key immediately
await authink.revokeAPIKey('key_abc123');

8

REST API Reference

All endpoints are available via our REST API at https://api.authink.app/v1. Use these endpoints directly if you prefer not to use our SDK.

Authentication

Include your API key in the Authorization header:

HTTP Headers

Authorization: Bearer sk_live_...
Content-Type: application/json

Endpoints

POST

/v1/otp/send

Send an OTP code to an email address

POST

/v1/otp/verify

Verify an OTP code submitted by user

POST

/v1/magic-link/send

Send a magic link for passwordless login

POST

/v1/sessions/verify

Validate a session token

DELETE

/v1/sessions/:id

Revoke a specific session

GET

/v1/keys

List all API keys

POST

/v1/keys

Create a new API key

Error Responses

All errors return a consistent JSON structure:

error.json

{
  error: {
    code: 'rate_limit_exceeded',
    message: 'Too many requests. Please try again in 60 seconds.',
    status: 429,
    retry_after: 60
  }
}

9

Security Best Practices

Follow these guidelines to ensure your integration remains secure and your users' data stays protected.

Keep API Keys Secret

Never expose API keys in client-side code, public repositories, or logs. Use environment variables or secret management systems like HashiCorp Vault or AWS Secrets Manager.

If you suspect a key has been exposed, revoke it immediately and create a new one.

Use Short Expiry Times

Set OTP expiration to 5 minutes or less. Shorter windows significantly reduce the attack window for brute-force attempts. For high-security applications, consider 2-3 minute expirations.

Implement Rate Limiting Client-Side

While Authink enforces server-side rate limits, implement client-side throttling too. Show users a countdown timer between resend attempts to improve UX and reduce API calls.

Validate Redirect URLs

When using magic links, always validate the redirect URL against an allowlist of authorized domains. Never trust user-provided redirect URLs without validation.

Store Tokens Securely

Store session tokens in httpOnly, secure, sameSite cookies when possible. If using localStorage (e.g., for SPAs), ensure your CSP headers prevent XSS attacks.

Log Security Events

Implement logging for authentication events: successful logins, failed attempts, suspicious patterns. Use these logs to detect potential attacks early.

10

Rate Limiting

Authink implements multiple layers of rate limiting to prevent abuse and ensure fair usage across all customers.

Endpoint Limits

Endpoint	Limit	Window	Scope
`POST /v1/otp/send`	10 requests	per minute	per email
`POST /v1/otp/send`	50 requests	per hour	per email
`POST /v1/otp/verify`	20 requests	per minute	per email
`POST /v1/magic-link/send`	5 requests	per hour	per email
All endpoints	Plan limit	monthly	per API key

Rate Limit Headers

Every API response includes rate limit headers so you can track your usage:

HTTP Response Headers

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1707673800
Retry-After: 30

Need higher limits? Growth and Enterprise plans include increased rate limits. Contact sales for custom limits tailored to your needs.