tapioca - Project Management

Tapioca supports multiple authentication methods depending on your use case.

API Tokens (Recommended)

API tokens are the simplest way to authenticate API requests. They’re ideal for:

Server-to-server integrations
CI/CD pipelines
Scripts and automation
CLI tools

Creating an API Token

Using API Tokens

Include the token in the Authorization header:

curl https://api.tapioca.dev/api/v1/tasks 
  -H "Authorization: Bearer tap_your_api_token_here"

Keep Tokens Secure

Never commit tokens to version control
Use environment variables in CI/CD
Rotate tokens regularly
Use minimal required scopes

Token Format

Tapioca API tokens follow this format:

tap_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

The tap_ prefix makes it easy to identify Tapioca tokens in your code and prevents accidental exposure in logs.

OAuth 2.0

For applications that act on behalf of users, use OAuth 2.0:

Supported Flows

Flow	Use Case
Authorization Code	Web applications
PKCE	Single-page apps, mobile apps
Client Credentials	Machine-to-machine

Authorization Code Flow

Redirect to authorization endpoint:

GET https://tapioca.dev/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  scope=read:tasks write:time&
  state=random_state_string

Exchange code for token:

POST https://tapioca.dev/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://your-app.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "tap_xxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tap_refresh_xxxxxxxx",
  "scope": "read:tasks write:time"
}

Refreshing Tokens

POST https://tapioca.dev/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=tap_refresh_xxxxxxxx&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Session Cookies

The web application uses HTTP-only session cookies. This is handled automatically by the browser and isn’t recommended for API integrations.

SSO / SAML

Enterprise customers using SSO can still use API tokens. Users authenticate via SSO to the dashboard, then create API tokens for programmatic access.

SSO Token Creation

Tokens created by SSO users inherit the user's organization permissions. When a user is deprovisioned via SSO, their tokens are automatically revoked.

Scopes Reference

Scope	Description
`read:tasks`	Read tasks, projects, sprints
`write:tasks`	Create, update, delete tasks
`read:time`	Read time entries and timesheets
`write:time`	Log and edit time entries
`read:finance`	Read budgets and transactions
`write:finance`	Create and update financial data
`read:users`	Read user profiles and teams
`admin:org`	Full organization administration
`admin:billing`	Manage billing and subscriptions

Best Practices

For Server Applications

// Store token in environment variable
const token = process.env.TAPIOCA_API_TOKEN;

// Create reusable client
const tapioca = {
  async request(endpoint, options = {}) {
    const response = await fetch(`https://api.tapioca.dev/api/v1${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }

    return response.json();
  }
};

// Use it
const tasks = await tapioca.request('/tasks');

For CI/CD Pipelines

# GitHub Actions example
env:
  TAPIOCA_TOKEN: ${{ secrets.TAPIOCA_API_TOKEN }}

steps:
  - name: Update task status
    run: |
      curl -X PATCH https://api.tapioca.dev/api/v1/tasks/$TASK_ID 
        -H "Authorization: Bearer $TAPIOCA_TOKEN" 
        -H "Content-Type: application/json" 
        -d '{"status": "done"}'

Troubleshooting

401 Unauthorized

Verify your token is correct and not expired
Check the token has required scopes
Ensure the Authorization header format is correct

403 Forbidden

Your token doesn’t have permission for this resource
Check organization membership
Verify required scopes are granted

Token Not Working After SSO Changes

Tokens may be revoked when user permissions change
Create a new token after permission updates

API Authentication