Getting Started
Authentication
Learn how to authenticate API requests and manage access tokens securely on 1st Services.
Authentication
All requests to the 1st Services REST API must be authenticated using an API key passed via the standard HTTP Authorization header.
Bearer Token Authentication
Include your API key as a Bearer token with every HTTP request:
HTTP Request
GET /v1/vps/instances HTTP/1.1
Host: api.1st-services.com
Authorization: Bearer fst_live_9a8b7c6d5e4f3a2b1c0d
Content-Type: application/json
cURL
curl -X GET "https://api.1st-services.com/v1/vps/instances" \
-H "Authorization: Bearer $FIRST_API_KEY"
Token Types & Prefixes
1st Services issues keys with explicit environment prefixes to prevent accidental exposure of production credentials:
| Key Type | Prefix | Description |
|---|---|---|
| Live / Production | fst_live_ | Accesses production VPS, active databases, live short links, and real mailboxes. |
| Test / Sandbox | fst_test_ | Operates against simulated staging resources without incurring billing charges. |
| Restricted Token | fst_res_ | Scoped to a specific microservice (e.g. Temp Mail only or URL Shortener only). |
Granular API Scopes
When creating an API key, you can restrict its permissions to only the capabilities required by your application:
| Scope | Permission Description |
|---|---|
vps:read | List instances, view specs, monitor CPU/RAM metrics |
vps:write | Create, reboot, rebuild, power-off, resize, delete VPS |
database:read | Inspect database connection strings, cluster status |
database:write | Provision databases, trigger backups, configure replicas |
shortener:* | Create, edit, delete, and view analytics for short links |
tempmail:* | Generate disposable mailboxes, fetch received messages |
billing:read | View invoices, usage metrics, and balance |
Webhook Signature Verification
When receiving webhooks from 1st Services (such as incoming Temp Mail alerts or Database Backup notifications), verify the authenticity of the payload using the X-1st-Signature header.
Signatures use HMAC-SHA256 with your webhook secret:
TypeScript / Node.js
import crypto from 'node:crypto'
export function verifyWebhookSignature(payload: string, signatureHeader: string, secret: string): boolean {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex')
return crypto.timingSafeEqual(
Buffer.from(signatureHeader),
Buffer.from(expectedSignature)
)
}
Security Best Practices
Protect Your Production API Keys