Authentication

Obtain access tokens and configure authentication

Authentication Overview (API v3)

SurveyNinja API uses API key authorization. Create a key in your account dashboard and pass it in the header Authorization: Bearer YOUR_API_TOKEN in all API v3 requests.

API v3 uses Laravel Sanctum. The key format is id|string, for example: 42|xK7mP9nQ2wL5eH8jR3vU6tY0iD4aF1bG.

How to get an API key

  1. 1 Log in to your SurveyNinja account
  2. 2 Go to Settings → API or directly at app.surveyninja.io/account/api
  3. 3 Click "Generate API key", set a name and copy the key — it is shown only once

Download the markdown version of the "Authentication" section for use in ChatGPT / other LLMs:

/static/api/authentication.md
AI Markdown

Current user info GET /api/v3/service/user

After obtaining a token, you can request information about the token owner.

GET /api/v3/service/user 
curl -X GET "https://api.surveyninja.io/api/v3/service/user" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Using a Bearer token

Add the token to the Authorization header of all protected API v3 requests:

GET /quiz 
curl -X GET https://api.surveyninja.io/api/v3/service/quiz \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

JavaScript (fetch)

fetch('https://api.surveyninja.io/api/v3/service/quiz', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Python (requests)

import requests

headers = {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.surveyninja.io/api/v3/service/quiz', headers=headers)
data = response.json()

PHP (cURL)

$url = 'https://api.surveyninja.io/api/v3/service/quiz';
$token = 'YOUR_TOKEN';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    echo json_encode($data, JSON_PRETTY_PRINT);
} else {
    echo "Error: HTTP $httpCode";
}

PHP (Guzzle)

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client();
$token = 'YOUR_TOKEN';

try {
    $response = $client->get('https://api.surveyninja.io/api/v3/service/quiz', [
        'headers' => [
            'Authorization' => 'Bearer ' . $token,
            'Content-Type' => 'application/json'
        ]
    ]);

    $data = json_decode($response->getBody(), true);
    echo json_encode($data, JSON_PRETTY_PRINT);
} catch (RequestException $e) {
    echo "Error: " . $e->getMessage();
}

Security best practices

Don't

  • Don't pass tokens in URL parameters
  • Don't commit tokens to public repositories
  • Don't expose tokens in client-side code
  • Don't share one token between different applications

Do

  • Store tokens in environment variables
  • Rotate tokens regularly
  • Use HTTPS for all requests

Authentication error handling

Error codes

Code Description Resolution
401 Invalid or missing token Check that the token in the Authorization header is correct
403 Token lacks access rights Check token permissions in settings
429 Rate limit exceeded Reduce request frequency or upgrade your plan