API Authentication

The VWire API supports two authentication methods: User API Keys (for programmatic access) and Session Tokens (for the dashboard's own requests). Third-party integrations should always use API Keys.

---

API Keys

Generate an API key

1. Go to Dashboard → Account → API Keys → New API Key
2. Give it a name and optional expiry
3. Copy the key — it is shown only once

API keys are prefixed with vwk_:

vwk_7f3a1c9e2b844d6fa913c5e28f01b77412ab34cd

Use in requests

GET /api/v1/devices
Authorization: Bearer vwk_7f3a1c9e2b844d6fa913c5e28f01b77412ab34cd

Scopes

Scope	Access
read:all	Read all resources
write:devices	Create and update devices
write:data	Write pin data
admin	Full access including billing

---

Session Tokens (dashboard use)

When you log in via the dashboard, a JWT session token is stored in httpOnly cookies. All dashboard requests are authenticated this way automatically. You don't need a session token for external API calls.

---

Login via API

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGci...",
    "user": {
      "id": "uuid",
      "email": "you@example.com",
      "name": "Jane"
    }
  }
}

Use the token as Authorization: Bearer <token> for subsequent requests. Tokens expire after 7 days.

---

Revoking API keys

DELETE /api/v1/auth/api-keys/{keyId}
Authorization: Bearer <your-token>

Revocation is instant — existing requests in-flight with the revoked key will fail.

---

Security best practices

tip

• Store API keys in environment variables, not source code
• Use the narrowest scope needed
• Set an expiry date on keys used in automation scripts
• Rotate keys regularly — quarterly minimum