Authentication

Cocobase provides a robust authentication system supporting both administrative API keys and per-user JWT tokens.

Authentication Methods

API Key Authentication

API keys are used for server-side operations and administrative tasks.

Header: X-API-Key: your_api_key or Authorization: Bearer your_api_key
Use Case: Cloud functions, backend integrations, administrative scripts.

JWT Token Authentication

User tokens are obtained after login and are used for client-side user operations.

Header: Authorization: Bearer <jwt_token>
Use Case: Frontend applications, mobile apps, user-specific data access.

Create a new user account.

Endpoint

POST /auth-collections/signup

Request Body

{
  "email": "user@example.com",
  "password": "securePassword123",
  "data": {
    "username": "johndoe",
    "name": "John Doe"
  }
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "data": { "username": "johndoe" }
  }
}

Authenticate an existing user.

Endpoint

POST /auth-collections/login

Request Body

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user_abc123",
    "email": "user@example.com"
  }
}

Get Current User

Retrieve the profile of the currently authenticated user.

Endpoint

GET /auth-collections/user

Headers

Authorization: Bearer <jwt_token>

Update User

Update the current user’s data. Supports atomic array operations.

Endpoint

PATCH /auth-collections/user

Atomic Array Operations

Use $append and $remove to modify array fields (like followers/following) without fetching-and-saving.

Follow a User ($append)

{
  "data": {
    "$append": { "following_ids": "user_target_456" }
  }
}

Unfollow a User ($remove)

{
  "data": {
    "$remove": { "following_ids": "user_target_456" }
  }
}

Update with File Upload

To update a user with files (e.g., avatar), use multipart/form-data.

curl -X PATCH https://api.cocobase.cc/auth-collections/user \
  -H "Authorization: Bearer <token>" \
  -F "data={\"bio\": \"New bio\"}" \
  -F "avatar=@/path/to/image.jpg"

Change Password

Update the user’s password.

Endpoint

POST /auth-collections/change-password

Request Body

{
  "old_password": "currentPassword123",
  "new_password": "newSecurePassword456"
}

List Users

List all users in the project. Requires API Key.

Endpoint

GET /auth-collections/users

Query Parameters

limit: Number of users to return
offset: Skip results for pagination
role: Filter by role
email_contains: Search by email content

Get User by ID

Retrieve a specific user’s public profile.

Endpoint

GET /auth-collections/users/{id}

OAuth Authentication

Cocobase supports Google and Apple OAuth.

1. Get OAuth Google URL

GET /auth-collections/oauth/google?redirect_uri=https://yourapp.com/callback POST /auth-collections/verify-google-login

{
  "code": "auth_code_from_google",
  "redirect_uri": "https://yourapp.com/callback"
}

User Relationships

Users can have relationships like followers and following. These are typically stored as arrays of IDs in the user data object.

Relationship	ID Pattern
Following	`following_ids`
Followers	`followers_ids`
Meta	`referral_code`

Examples

JavaScript
Python

// Register
const signup = await fetch('https://api.cocobase.cc/auth-collections/signup', {
  method: 'POST',
  body: JSON.stringify({ email, password, data })
});

// Update (Follow)
await fetch('https://api.cocobase.cc/auth-collections/user', {
  method: 'PATCH',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({
    data: { "$append": { "following_ids": targetId } }
  })
});

import requests

# Login
res = requests.post('https://api.cocobase.cc/auth-collections/login', 
                   json={'email': email, 'password': password})
token = res.json()['access_token']

# Get User
user = requests.get('https://api.cocobase.cc/auth-collections/user',
                   headers={'Authorization': f'Bearer {token}'}).json()

Best Practices

Security: Never expose Live API keys (sk_live_...) in client-side code.
Tokens: Refresh JWT tokens before they expire to maintain session persistence.
Atomic Operations: Always use $append and $remove for array updates to avoid race conditions.
Validation: Validate email formats and password strength on the frontend before submitting to the API.

Rate Limits

Tier	Limit
Free	60 requests / minute
Pro	1000 requests / minute
Enterprise	Custom

​Authentication

​Authentication Methods

​API Key Authentication

​JWT Token Authentication

​Sign Up

​Endpoint

​Request Body

​Response

​Login

​Endpoint

​Request Body

​Response

​Get Current User

​Endpoint

​Headers

​Update User

​Endpoint

​Atomic Array Operations

​Follow a User ($append)

​Unfollow a User ($remove)

​Update with File Upload

​Change Password

​Endpoint

​Request Body

​List Users

​Endpoint

​Query Parameters

​Get User by ID

​Endpoint

​OAuth Authentication

​1. Get OAuth Google URL

​2. Verify Google Login

​User Relationships

​Examples

​Best Practices

​Rate Limits

Authentication

Authentication Methods

API Key Authentication

JWT Token Authentication

Sign Up

Endpoint

Request Body

Response

Login

Endpoint

Request Body

Response

Get Current User

Endpoint

Headers

Update User

Endpoint

Atomic Array Operations

Follow a User ($append)

Unfollow a User ($remove)

Update with File Upload

Change Password

Endpoint

Request Body

List Users

Endpoint

Query Parameters

Get User by ID

Endpoint

OAuth Authentication

1. Get OAuth Google URL

2. Verify Google Login

User Relationships

Examples

Best Practices

Rate Limits