API authentication

API Authentication

Learn how to authenticate with our API securely.

Authentication Methods

Method	Use Case	Security
API Key	Server-to-server	High
OAuth 2.0	User-authorized apps	Highest
Session Token	Temporary access	Medium

API Key Authentication

The simplest method for server applications.

Using Bearer Token

curl -X GET https://api.osir.com/v1/domains \
  -H "Authorization: Bearer osir_live_your_api_key"

Using X-API-Key Header

curl -X GET https://api.osir.com/v1/domains \
  -H "X-API-Key: osir_live_your_api_key"

OAuth 2.0 Authentication

For applications acting on behalf of users.

Step 1: Redirect to Authorization

https://osir.com/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=domains:read domains:write

Step 2: Exchange Code for Token

curl -X POST https://api.osir.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=authorization_code_here" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "redirect_uri=https://yourapp.com/callback"

Step 3: Use Access Token

curl -X GET https://api.osir.com/v1/domains \
  -H "Authorization: Bearer access_token_here"

Token Refresh

Access tokens expire after 1 hour. Use refresh tokens:

curl -X POST https://api.osir.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=your_refresh_token" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Scopes

Scope	Description
domains:read	View domains
domains:write	Manage domains
vps:read	View servers
vps:write	Manage servers
email:read	View email settings
email:write	Manage email
billing:read	View billing info
billing:write	Manage billing

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

{
  "error": "forbidden",
  "message": "Insufficient permissions for this action"
}

Security Best Practices

HTTPS only - Never send credentials over HTTP
Short-lived tokens - Use refresh tokens for long sessions
Minimum scopes - Request only what you need
Secure storage - Never expose secrets in client-side code
Rotate secrets - Regularly update client secrets