Authentication

Postpone uses personal API tokens to authenticate requests against the GraphQL API. This guide covers how to obtain your API token, use it in requests, and best practices for API authentication.

Getting Your API Token

To access Postpone's API, you'll need to generate a personal API token from your account settings.

Step-by-step instructions:

1. Log into your Postpone account at postpone.app
2. Navigate to Settings from the main navigation
3. Scroll down to the API Token section
4. Click Retrieve Token to view your existing token, or Regenerate Token to create a fresh one

Using Your API Token

API tokens must be included in the Authorization header of every request to Postpone's API. Use the Bearer authentication scheme with your token.

Header format:

Authorization: Bearer YOUR-API-TOKEN

Complete request example:

curl --request POST \
  --url https://api.postpone.app/gql \
  --header 'Authorization: Bearer YOUR-API-TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "query profile { profile { id username email } }"
  }'

Authentication Examples

const response = await fetch('https://api.postpone.app/gql', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR-API-TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `
      query profile {
        profile {
          id
          username
          email
        }
      }
    `
  })
});

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR-API-TOKEN',
    'Content-Type': 'application/json',
}

query = """
query profile {
  profile {
    id
    username
    email
  }
}
"""

response = requests.post(
    'https://api.postpone.app/gql',
    headers=headers,
    json={'query': query}
)

data = response.json()

Token Security Best Practices

Environment Variables

Store your API token in environment variables rather than hardcoding it in your application:

# .env file
POSTPONE_API_TOKEN=your-api-token-here

// In your application
const token = process.env.POSTPONE_API_TOKEN;

Token Rotation

Regularly rotate your API tokens for enhanced security:

1. Generate a new token in your Settings
2. Update your applications to use the new token
3. Test that everything works with the new token
4. The old token will be automatically invalidated when you generate a new one

Troubleshooting Authentication

Common authentication errors:

401 Unauthorized

• Your API token is missing, invalid, or expired
• Make sure you're including the Bearer prefix in the Authorization header

403 Forbidden

• Your account doesn't have access to the API (requires a paid plan)
• The token may belong to a different account

Invalid token format

• Ensure you're using Bearer YOUR-TOKEN format
• Check for extra spaces or characters in your token

Testing your authentication:

Use this simple query to test if your authentication is working:

curl --request POST \
  --url https://api.postpone.app/gql \
  --header 'Authorization: Bearer YOUR-API-TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"query": "query { profile { username } }"}'

A successful response will return your username:

{
  "data": {
    "profile": {
      "username": "your-username"
    }
  }
}