Developer API

Build with Battora Vault

Access the creator identity layer. Connect artists to your apps through our unified API — one integration for discovery, data, and creative collaboration.

RESTful API

Simple, predictable REST endpoints for fetching artist profiles, portfolio items, achievements, and rate cards.

Unified Data Model

Access structured creative data — from social links to portfolio pieces — through a single, consistent API.

API Key Authentication

Secure API key-based auth with usage tracking and rate limiting. Get started in minutes.

What is Battora Vault?

Battora Vault is the creator identity layer for the modern web. It's a unified profile system where creative data actually works for developers and artists alike.

Our API connects your applications to verified artist profiles — giving you instant access to portfolios, achievements, social links, and rate cards through a single integration point.

Whether you're building a marketplace, booking platform, or discovery tool, Battora Vault provides the infrastructure to power creative connections at scale.

Integration Options

REST API

Direct API access for fetching creator data, portfolios, and rate cards. Perfect for backend integrations.

OAuth 2.0 + JavaScript SDK

"Sign in with Battora" authentication. Let users connect their creator profiles to your app.

Sign in with Battora - JavaScript SDK

Add "Sign in with Battora" to your website in minutes. No build tools required — just include our SDK and you're ready to go.

1Include the SDK

<!-- Add this to your HTML <head> or before closing </body> -->
<script src="https://vault.battora.com/sdk/battora-auth.js"></script>

2Initialize with your Client ID

<script>
BattoraAuth.init({
clientId: 'your-client-id',
redirectUri: 'https://yourapp.com/callback'
});
</script>
💡 Get your Client ID from the API Dashboard

3Add a Sign In Button

<!-- Option A: Pre-styled button (easiest) -->
<div id="battora-signin"></div>
<script>
BattoraAuth.renderButton('#battora-signin', {
theme: 'dark' // or 'light'
});
</script>
<!-- Option B: Custom button -->
<button onclick="BattoraAuth.signIn()">
Sign in with Battora
</button>

4Handle the Callback

<script>
// Called when user signs in successfully
BattoraAuth.onSuccess(async (result) => {
// Send code to your backend for token exchange
const response = await fetch('/api/auth/battora', {
method: 'POST',
body: JSON.stringify({ code: result.code })
});
const user = await response.json();
console.log('User authenticated:', user);
});
</script>

Try it Now

Test the SDK with a live interactive demo:

⚠️ Important: Backend Token Exchange

For security, the authorization code must be exchanged for an access token on your backend (never client-side). Your backend needs to call:

POST
https://vault.battora.com/api/oauth/token
With parameters:
grant_type, code, redirect_uri, client_id, client_secret

Third-Party Integration Guide

Complete guide for integrating "Sign in with Battora Vault" into your applications. Support for all major frameworks and platforms.

Multi-Role Authentication

Support for Creators, Brands, and Developers with role-specific data access.

Enterprise Security

OAuth 2.0 with PKCE, refresh tokens, and comprehensive scope management.

Framework Agnostic

Works with React, Next.js, Express, vanilla JS, and any OAuth-compatible system.

Authentication Flow

1

User Clicks Sign In

Your button triggers the OAuth flow

2

Account Selection

User chooses Creator, Brand, or Developer

3

Authentication

User signs in or completes onboarding

4

Return to App

User redirected with authorization code

Framework Integration Examples

React Integration

// hooks/useBattoraAuth.js
import
{ useState, useEffect } from 'react'
export function useBattoraAuth() {
const [user, setUser] = useState(null)
const [loading, setLoading] = useState(true)
// Authentication logic here...
return { user, signIn, signOut, isAuthenticated }
}

Next.js with NextAuth

// pages/api/auth/[...nextauth].ts
import
NextAuth from 'next-auth'
export default NextAuth({
providers: [
{
id: 'battora-vault',
name: 'Battora Vault',
type: 'oauth',
clientId: process.env.BATTORA_CLIENT_ID,
authorization: 'https://vault.battora.com/api/oauth/authorize'
}
]
});

Express.js Backend

// routes/auth.js
router.get('/oauth/callback', async (req, res) => {)
const {code, state} = req.query
// Exchange code for tokens
const tokenResponse = await fetch('https://vault.battora.com/api/oauth/token', {
method: 'POST',
body: new URLSearchParams({ code, client_id, client_secret })
});
});

Security Best Practices

Secure Token Storage

✅ Access tokens (short-lived)
sessionStorage.setItem('token', accessToken)
✅ Refresh tokens (long-lived)
httpOnly cookies with Secure flag
❌ Never store in localStorage
localStorage.setItem('token', token)

CSRF Protection

Generate cryptographically secure state
const state = crypto.randomUUID()
Verify on callback
if (returnedState !== storedState) throw Error

PKCE for Public Clients

Generate code verifier & challenge
const verifier = generateRandomString(64)
const challenge = await sha256(verifier)
Include in authorization request
code_challenge_method=S256

Production Requirements

✅ Always use HTTPS in production
https://vault.battora.com
⚠️ HTTP only for local development
http://localhost:3000

Available Scopes & Permissions

openid

Basic OpenID Connect identifier access

Provides: sub
profile

Basic profile information

Provides: name, picture, role
email

Email address and verification status

Provides: email, email_verified
creator

Creator-specific profile data

Provides: creatorProfileId, artist info
brands

Brand associations and roles

Provides: brands[] array with roles

Common Scope Combinations

Minimal authentication:
openid profile
Full music platform access:
openid profile email creator brands
Creator-only platform:
openid profile email creator

Error Handling & Debugging

Common OAuth Errors

invalid_client

Wrong client credentials

Check client_id and client_secret
invalid_grant

Authorization code expired

Codes expire in 10 minutes
access_denied

User declined authorization

Handle gracefully in UI
invalid_request

Malformed request

Check required parameters

Error Handling Example

try
{ // Token exchange }
catch
switch (error.error) {
case 'access_denied':
// User cancelled - show friendly message
break
case 'invalid_client':
// Configuration error - log for debugging
break
}

Testing & Development

Development Environment

Base URL for local testing:
http://localhost:3000
Test redirect URI:
http://localhost:8080/callback

Live Demo

Test the complete OAuth flow with our interactive demo.

Getting OAuth Credentials

To register your application for OAuth access:

  1. 1. Email support@vault.battora.com with your application details
  2. 2. Include your intended use case and redirect URIs
  3. 3. Provide business/organization information
  4. 4. Receive your client_id and client_secret within 1-2 business days
Contact: support@vault.battora.com

REST API Endpoints

# Get artist profile
GET https://vault.battora.com/api/artists/:id
# Get artist portfolio
GET https://vault.battora.com/api/artists/:id/portfolio
# Get rate cards
GET https://vault.battora.com/api/artists/:id/rate-cards
# Authentication
Authorization: Bearer YOUR_API_KEY

Ready to integrate?

Access your API dashboard to generate keys and start building.