API Authentication Guide

Learn how to authenticate with the FormRobin API using JWT tokens for secure programmatic access to your forms and data.

Authentication Overview

The FormRobin API uses Bearer token authentication with JWT (JSON Web Tokens). This authentication method:

• Provides secure, stateless authentication
• Doesn't require session management
• Uses your FormRobin email and password to generate tokens
• Tokens expire after a set period for security
• Works across all API endpoints

Authentication Flow

1. Login: Send your credentials to the login endpoint
2. Receive Token: Get an access token in the response
3. Use Token: Include the token in the Authorization header for all requests
4. Token Expires: Re-authenticate when the token expires

Obtaining an Access Token

Login Endpoint

POST https://forms.formrobin.com/api/jwt/login

Request Format

Headers:

Content-Type: application/json
Accept: application/json

Body (JSON):

{
  "email": "your-email@example.com",
  "password": "your-password"
}

Alternatively, you can use username  instead of email :

{
  "username": "your-email@example.com",
  "password": "your-password"
}

Success Response

Status: 200 OK

Body:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer",
  "expires_in": 31536000
}

• access: Your JWT token (store this securely)
• token_type: Always "bearer"
• expires_in: Token lifetime in seconds (typically 1 year)

Error Response

Status: 401 Unauthorized

Body:

{
  "error": "Unauthorized"
}

This error means your email or password is incorrect.

Using Your Access Token

Once you have a token, include it in the Authorization  header of all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Complete Example Request

GET https://forms.formrobin.com/api/v1/forms

Headers:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json
Accept: application/json

Code Examples

cURL Example

# Step 1: Login and get token
curl -X POST https://forms.formrobin.com/api/jwt/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

# Step 2: Use token in subsequent requests
curl -X GET https://forms.formrobin.com/api/v1/forms \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

JavaScript (Fetch API) Example

// Step 1: Login
const loginResponse = await fetch('https://forms.formrobin.com/api/jwt/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    email: 'your-email@example.com',
    password: 'your-password'
  })
});

const { access: token } = await loginResponse.json();

// Step 2: Use token
const formsResponse = await fetch('https://forms.formrobin.com/api/v1/forms', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json'
  }
});

const forms = await formsResponse.json();

Python (requests) Example

import requests

# Step 1: Login
login_url = 'https://forms.formrobin.com/api/jwt/login'
login_data = {
    'email': 'your-email@example.com',
    'password': 'your-password'
}
login_response = requests.post(login_url, json=login_data)
token = login_response.json()['access']

# Step 2: Use token
forms_url = 'https://forms.formrobin.com/api/v1/forms'
headers = {
    'Authorization': f'Bearer {token}',
    'Accept': 'application/json'
}
forms_response = requests.get(forms_url, headers=headers)
forms = forms_response.json()

Storing Tokens Securely

Best Practices:

• Server-side only: Never expose tokens in client-side JavaScript or mobile apps
• Environment variables: Store tokens in environment variables, not in code
• Encrypted storage: Encrypt tokens when storing in databases
• Never commit: Don't commit tokens to version control (Git)
• Rotate regularly: Regenerate tokens periodically for security

Handling Token Expiration

Tokens expire after the time specified in expires_in  (typically 1 year). When a token expires:

1. API requests return 401 Unauthorized
2. You must obtain a new token by logging in again
3. No refresh token mechanism is currently available

Recommended Strategy

// Pseudo-code for handling expiration
function makeApiRequest(url) {
  response = fetch(url, { headers: { Authorization: `Bearer ${token}` } });
  
  if (response.status === 401) {
    // Token expired - login again
    token = loginAndGetNewToken();
    // Retry the request
    response = fetch(url, { headers: { Authorization: `Bearer ${token}` } });
  }
  
  return response;
}

Checking Authentication Status

To verify your token is valid and get current user info:

GET https://forms.formrobin.com/api/user

Headers:

Authorization: Bearer YOUR_TOKEN
Accept: application/json

Response:

{
  "id": 123,
  "name": "Your Name",
  "email": "your-email@example.com",
  "tier_level": 1,
  ...
}

Security Best Practices

• HTTPS only: Always use HTTPS for API requests
• Strong passwords: Use a strong password for your FormRobin account
• Token rotation: Regenerate tokens if you suspect compromise
• Least privilege: Only share tokens with authorized systems
• Monitor usage: Watch for unexpected API activity
• Secure transmission: Never send tokens via unencrypted channels

Limitations

• No refresh tokens: Must re-authenticate when token expires
• No API keys: Only JWT bearer tokens are supported
• No OAuth: FormRobin doesn't support OAuth for third-party apps
• Account-level access: Tokens grant full access to your account
• No scopes: Cannot limit token permissions

Troubleshooting

Issue: 401 Unauthorized when logging in.

Fix: Verify your email and password are correct. Check that your account is active and not suspended. Ensure you're sending the request to the correct endpoint (/api/jwt/login ). Try logging in via the website first to confirm credentials.

Issue: 401 Unauthorized on API requests (but login worked).

Fix: Verify the Authorization header is formatted correctly: Authorization: Bearer YOUR_TOKEN  (note the space after "Bearer"). Check that the token hasn't expired. Ensure you're using the access  value from the login response, not the entire response object.

Issue: Token format looks wrong or truncated.

Fix: JWT tokens are long strings (typically 500+ characters). Ensure you're storing and sending the complete token. Check for any string truncation or encoding issues in your code.

Issue: Getting CORS errors in browser.

Fix: The API is meant for server-side use. If you must use it client-side, ensure your domain is whitelisted. Consider proxying requests through your backend instead of calling the API directly from the browser.

FAQ

Q: How long do access tokens last?

A: Tokens typically last for 1 year (31536000 seconds). The exact duration is returned in the expires_in  field when you login.

Q: Can I use one token across multiple applications?

A: Yes, but it's not recommended. If one application is compromised, all applications are at risk. Consider using separate accounts for different applications if possible.

Q: Is there a way to revoke a token?

A: Currently, there's no token revocation endpoint. To invalidate a token, change your account password. This will invalidate all existing tokens.

Q: Can I generate tokens without a password?

A: No. API keys or password-less authentication are not currently supported. You must use your account credentials to generate tokens.

Need help with API authentication? Contact our support team - we're here to help!