Skip to main content

🔌 Authentication API

PasskeyMe provides a comprehensive REST API for authentication operations. While we recommend using our SDKs for most use cases, the direct API is useful for server-side operations, custom integrations, and non-JavaScript environments.

Base URL

Production: https://api.passkeyme.com
Development: https://dev-api.passkeyme.com

Authentication

API requests require authentication using your App ID and API key from the PasskeyMe dashboard.

API Key Authentication

Authorization: Bearer your-api-key
Content-Type: application/json

App ID Header

X-PasskeyMe-App-ID: your-app-id

Core Endpoints

Initiate Authentication

Start the authentication process and get a redirect URL.

POST /auth/initiate

Request:

{
"redirectUri": "https://yourapp.com/auth/callback",
"authMethod": "passkey|oauth|password",
"provider": "google|github|microsoft|apple|discord",
"state": "custom-state-data"
}

Response:

{
"authUrl": "https://auth.passkeyme.com/authenticate/abc123",
"sessionId": "sess_1234567890",
"expiresAt": "2024-01-01T12:00:00Z"
}

Handle Callback

Process the authentication callback and get tokens.

POST /auth/callback

Request:

{
"code": "auth_code_from_callback",
"state": "original_state_value",
"sessionId": "sess_1234567890"
}

Response:

{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "refresh_token_value",
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"emailVerified": true,
"name": "John Doe",
"picture": "https://example.com/avatar.jpg",
"createdAt": "2024-01-01T10:00:00Z",
"lastLoginAt": "2024-01-01T12:00:00Z",
"authMethods": {
"passkey": true,
"oauth": ["google"],
"password": false
}
},
"expiresIn": 3600
}

Refresh Token

Get a new access token using a refresh token.

POST /auth/refresh

Request:

{
"refreshToken": "refresh_token_value"
}

Response:

{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "new_refresh_token_value",
"expiresIn": 3600
}

Validate Token

Verify and decode an access token.

GET /auth/validate
Authorization: Bearer access_token_here

Response:

{
"valid": true,
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"emailVerified": true,
"name": "John Doe"
},
"scopes": ["profile", "email"],
"expiresAt": "2024-01-01T13:00:00Z"
}

Logout

Revoke tokens and end the session.

POST /auth/logout
Authorization: Bearer access_token_here

Request:

{
"refreshToken": "refresh_token_to_revoke",
"allSessions": false
}

Response:

{
"success": true,
"message": "Successfully logged out"
}

User Management

Get User Profile

Retrieve complete user profile information.

GET /users/profile
Authorization: Bearer access_token_here

Response:

{
"id": "usr_1234567890",
"email": "user@example.com",
"emailVerified": true,
"name": "John Doe",
"picture": "https://example.com/avatar.jpg",
"createdAt": "2024-01-01T10:00:00Z",
"lastLoginAt": "2024-01-01T12:00:00Z",
"authMethods": {
"passkey": true,
"oauth": ["google", "github"],
"password": true
},
"metadata": {
"loginCount": 42,
"lastIpAddress": "192.168.1.1",
"userAgent": "Mozilla/5.0..."
}
}

Update User Profile

Update user profile information.

PATCH /users/profile
Authorization: Bearer access_token_here

Request:

{
"name": "Jane Doe",
"picture": "https://newavatar.com/avatar.jpg"
}

Response:

{
"id": "usr_1234567890",
"email": "user@example.com",
"name": "Jane Doe",
"picture": "https://newavatar.com/avatar.jpg",
"updatedAt": "2024-01-01T12:30:00Z"
}

Delete User Account

Permanently delete a user account.

DELETE /users/profile
Authorization: Bearer access_token_here

Response:

{
"success": true,
"message": "Account successfully deleted"
}

Authentication Methods

List User Auth Methods

Get all authentication methods for a user.

GET /users/auth-methods
Authorization: Bearer access_token_here

Response:

{
"methods": [
{
"type": "passkey",
"id": "passkey_1234",
"name": "iPhone Touch ID",
"createdAt": "2024-01-01T10:00:00Z",
"lastUsed": "2024-01-01T12:00:00Z"
},
{
"type": "oauth",
"provider": "google",
"id": "oauth_5678",
"email": "user@gmail.com",
"createdAt": "2024-01-01T10:00:00Z",
"lastUsed": "2024-01-01T11:00:00Z"
}
]
}

Add Authentication Method

Add a new authentication method to user's account.

POST /users/auth-methods
Authorization: Bearer access_token_here

Request:

{
"type": "passkey|oauth|password",
"provider": "google", // for OAuth only
"redirectUri": "https://yourapp.com/add-auth/callback"
}

Response:

{
"authUrl": "https://auth.passkeyme.com/add-method/abc123",
"sessionId": "sess_add_1234567890",
"expiresAt": "2024-01-01T12:30:00Z"
}

Remove Authentication Method

Remove an authentication method from user's account.

DELETE /users/auth-methods/{methodId}
Authorization: Bearer access_token_here

Response:

{
"success": true,
"message": "Authentication method removed"
}

Application Management

Get Application Info

Retrieve application configuration and statistics.

GET /applications/{appId}
Authorization: Bearer api_key_here

Response:

{
"id": "app_1234567890",
"name": "My Application",
"domain": "myapp.com",
"redirectUris": [
"https://myapp.com/auth/callback",
"http://localhost:3000/auth/callback"
],
"authMethods": {
"passkey": {
"enabled": true,
"required": false
},
"oauth": {
"enabled": true,
"providers": ["google", "github"]
},
"password": {
"enabled": false
}
},
"branding": {
"logo": "https://myapp.com/logo.png",
"primaryColor": "#007bff",
"companyName": "My Company"
},
"stats": {
"totalUsers": 1250,
"activeUsers": 980,
"totalLogins": 15670
}
}

Update Application Settings

Update application configuration.

PATCH /applications/{appId}
Authorization: Bearer api_key_here

Request:

{
"name": "Updated App Name",
"redirectUris": [
"https://myapp.com/auth/callback",
"https://staging.myapp.com/auth/callback"
],
"authMethods": {
"passkey": {
"enabled": true,
"required": true
}
}
}

Webhooks

Authentication Events

PasskeyMe can send webhooks for authentication events.

Webhook endpoint configuration:

POST /webhooks/endpoints
Authorization: Bearer api_key_here

Request:

{
"url": "https://yourapi.com/webhooks/passkeyme",
"events": ["user.login", "user.logout", "user.created"],
"secret": "webhook_secret_key"
}

Webhook payload example:

{
"event": "user.login",
"timestamp": "2024-01-01T12:00:00Z",
"data": {
"userId": "usr_1234567890",
"email": "user@example.com",
"authMethod": "passkey",
"ipAddress": "192.168.1.1",
"userAgent": "Mozilla/5.0...",
"sessionId": "sess_1234567890"
}
}

Error Handling

Error Response Format

All API errors follow a consistent format:

{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": "Additional error details",
"requestId": "req_1234567890"
}
}

Common Error Codes

CodeHTTP StatusDescription
INVALID_APP_ID401Invalid or missing App ID
INVALID_API_KEY401Invalid or missing API key
INVALID_TOKEN401Invalid or expired access token
INSUFFICIENT_SCOPE403Token doesn't have required scope
USER_NOT_FOUND404User doesn't exist
METHOD_NOT_FOUND404Authentication method not found
INVALID_REQUEST400Malformed request body
RATE_LIMITED429Too many requests
SERVER_ERROR500Internal server error

Error Handling Example

async function apiCall(endpoint, options = {}) {
try {
const response = await fetch(`https://api.passkeyme.com${endpoint}`, {
headers: {
'Authorization': `Bearer ${apiKey}`,
'X-PasskeyMe-App-ID': appId,
'Content-Type': 'application/json'
},
...options
});

if (!response.ok) {
const error = await response.json();
throw new Error(`API Error: ${error.error.code} - ${error.error.message}`);
}

return await response.json();
} catch (error) {
console.error('API call failed:', error);
throw error;
}
}

Rate Limits

API endpoints have the following rate limits:

Endpoint TypeRate LimitWindow
Authentication100 requests1 minute
User Management500 requests1 minute
Application Management100 requests1 minute
Webhooks1000 requests1 minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

SDK Integration

Using API with SDKs

Most operations are handled by SDKs, but you can access the underlying API:

// JavaScript SDK
import { PasskeymeAuth } from '@passkeyme/auth';

const auth = new PasskeymeAuth({ appId: 'your-app-id' });

// Make direct API call
const apiResponse = await auth.apiCall('/users/profile', {
method: 'PATCH',
body: JSON.stringify({ name: 'New Name' })
});

Server-Side Usage

Use the API directly for server-side operations:

// Node.js example
const express = require('express');
const app = express();

app.get('/api/user', async (req, res) => {
const token = req.headers.authorization?.replace('Bearer ', '');

try {
const userResponse = await fetch('https://api.passkeyme.com/users/profile', {
headers: {
'Authorization': `Bearer ${token}`,
'X-PasskeyMe-App-ID': process.env.PASSKEYME_APP_ID
}
});

const user = await userResponse.json();
res.json(user);
} catch (error) {
res.status(401).json({ error: 'Unauthorized' });
}
});

Testing

Test Endpoints

Development environment provides test endpoints:

Base URL: https://dev-api.passkeyme.com

Postman Collection

Download our Postman collection for API testing:

{
"info": {
"name": "PasskeyMe API",
"description": "Complete API collection for PasskeyMe"
},
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{api_key}}",
"type": "string"
}
]
}
}

API Testing Examples

# Test authentication initiation
curl -X POST https://api.passkeyme.com/auth/initiate \
-H "Authorization: Bearer your-api-key" \
-H "X-PasskeyMe-App-ID: your-app-id" \
-H "Content-Type: application/json" \
-d '{
"redirectUri": "https://yourapp.com/callback",
"authMethod": "passkey"
}'

# Test token validation
curl -X GET https://api.passkeyme.com/auth/validate \
-H "Authorization: Bearer user-access-token" \
-H "X-PasskeyMe-App-ID: your-app-id"

Next Steps