Authentication

All API requests require a Project Token. The token identifies your organization and authorizes requests to identify users and track events.

Getting your Project Token

Go to Settings and copy your Project Token (it starts with rk-)

Although the Project Token is write-only, we recommend using it only on the backend.

Using the Project Token

In Node.js, pass the token when creating the Retain client and the SDK handles authentication automatically. In other languages, include the token in each request using Authorization: Basic <token> with Content-Type: application/json.

import { Retain } from '@retain-so/sdk';

const retain = new Retain(process.env.RETAIN_WRITE_KEY);

import os
import requests

requests.post(
    'https://api.retain.so/identify',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Basic {os.environ["RETAIN_WRITE_KEY"]}',
    },
    json={
        'userId': 'user_123',
        'email': '[email protected]',
    },
)

$ch = curl_init('https://api.retain.so/identify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Basic ' . getenv('RETAIN_WRITE_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'userId' => 'user_123',
        'email' => '[email protected]',
    ]),
]);
curl_exec($ch);
curl_close($ch);

require 'net/http'
require 'json'

uri = URI('https://api.retain.so/identify')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['Authorization'] = "Basic #{ENV.fetch('RETAIN_WRITE_KEY')}"
req.body = { userId: 'user_123', email: '[email protected]' }.to_json

Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String json = """
  {"userId":"user_123","email":"[email protected]"}
  """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.retain.so/identify"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Basic " + System.getenv("RETAIN_WRITE_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

curl -X POST https://api.retain.so/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $RETAIN_WRITE_KEY" \
  -d '{
    "userId": "user_123",
    "email": "[email protected]"
  }'

See Identify and Track for the same pattern with full request bodies in each language.

Introduction

Quickstart

Integrations

Authentication

Getting your Project Token

Using the Project Token

Next steps

Identify

Track

​Getting your Project Token

​Using the Project Token

​Next steps

Identify

Track

Getting your Project Token

Using the Project Token

Next steps