Authentication

All RasnuCloud API requests are authenticated using Bearer tokens. Tokens are scoped and revocable — you can create different tokens for different systems with only the permissions each one needs.

---

Creating an API Token

From the dashboard:

1. Go to Profile → API Tokens
2. Click New Token
3. Give it a descriptive name (e.g., "GitHub Actions — Production", "Monitoring System")
4. Select the scopes this token needs
5. Copy the token immediately — it is shown only once

---

Using the Token

Include it as a Bearer token in the Authorization header of every request:

GET /api/v1/servers
Authorization: Bearer your_token_here
Content-Type: application/json

---

Token Scopes

Create tokens with only the permissions your integration needs.

Scope	What It Allows
*	Full access to all API endpoints
servers:read	List servers and read their status and configuration
servers:manage	Add, update, and remove servers
conversations:create	Start conversations and trigger command execution
conversations:read	Read conversation history and step results
deployments:run	Trigger deployment workflow runs
audit:read	Read the organization audit log

---

Rate Limits

Every token is limited to 60 requests per minute. If you exceed this, you'll receive:

HTTP/1.1 429 Too Many Requests
Retry-After: 34
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

Wait for the number of seconds in Retry-After, then retry.

---

IP Restrictions

If your organization has IP allowlisting enabled, API requests from non-allowed IPs receive:

HTTP/1.1 403 Forbidden

{
  "error": "Your IP address is not authorized."
}

If you're integrating from a CI/CD system, ensure the system's outbound IP is on your allowlist.

---

Revoking a Token

Revoke a token immediately if it's compromised or no longer needed:

From the dashboard: Profile → API Tokens → Revoke

From the API:

DELETE /api/v1/auth/tokens/{token_id}
Authorization: Bearer your_token_here

Revoked tokens are rejected immediately — no propagation delay.