Authentication
Issue and refresh access tokens, close sessions, and retrieve the current profile.
/security-api/api/v1/auth
Quick start
Make your first authenticated request
Use the base URL assigned to your environment. The examples below use environment variables so credentials never appear in source code.
1
1. Set the base URL
Store the environment origin, such as https://devm.hyperionwave.com, in BASE_URL.
2
2. Obtain a JWT
Authenticate with Security API, then keep the access token in a secure runtime variable.
3
3. Call a service
Add the service prefix, send JSON or multipart data, and handle every non-2xx status explicitly.
Security API
Authentication endpoints
Base path: /security-api/api/v1/auth
Send the access token on protected requests as Authorization: Bearer <JWT>. Keep access and refresh tokens out of logs, URLs, analytics events, and browser storage you do not control.
- POST /login — authenticate with local credentials or a supported identity provider
- POST /refresh — exchange a refresh token for a current token pair
- POST /logout — close the active session
- GET /profile — retrieve the authenticated user's profile
- POST /validate — validate a JWT in a trusted service integration
Payload example
Login and refresh tokens
Login request
POST /security-api/api/v1/auth/login
{
"provider": "local",
"email": "developer@example.com",
"password": "<password>"
}
Login response
{
"accessToken": "eyJ...",
"refreshToken": "eyJ...",
"tokenType": "Bearer",
"expiresIn": 3600,
"companyRequired": false,
"user": {
"id": "usr_4f8d2",
"email": "developer@example.com",
"name": "Alex Morgan",
"companyId": "cmp_91ab",
"roles": ["member"]
}
}
Refresh request
POST /security-api/api/v1/auth/refresh
{
"refreshToken": "eyJ..."
}
Payload example
Create a table and store a record
Create a schema
POST /data-api/api/v1/schemas
{
"table": "orders",
"description": "Customer orders received from the commerce platform",
"fields": [
{ "name": "customerId", "type": "string", "required": true },
{ "name": "amount", "type": "number", "required": true },
{
"name": "status",
"type": "string",
"required": true,
"enum": ["open", "approved", "rejected"]
}
]
}
Store a record
POST /data-api/api/v1/data
{
"table": "orders",
"data": {
"customerId": "cus_8021",
"amount": 249.95,
"status": "open"
},
"metadata": {
"source": "commerce-sync",
"correlationId": "req_7b21"
}
}
Store response
{
"success": true,
"table": "orders",
"recordId": "67a2f98c41b6d2a71f003e12",
"validated": true,
"verified": true,
"timestamp": "2026-08-11T09:30:00Z"
}
Payload example
Query records with filters and pagination
Query request
POST /data-api/api/v1/data/query
{
"table": "orders",
"filters": {
"status": "open",
"amount": { "$gte": 100 }
},
"projection": { "customerId": 1, "amount": 1, "status": 1 },
"sort": { "amount": -1 },
"limit": 25,
"offset": 0
}
Query response
{
"table": "orders",
"records": [
{
"recordId": "67a2f98c41b6d2a71f003e12",
"table": "orders",
"data": {
"customerId": "cus_8021",
"amount": 249.95,
"status": "open"
},
"version": 1,
"createdAt": "2026-08-11T09:30:00Z"
}
],
"totalRecords": 1,
"returnedRecords": 1,
"hasMore": false
}
Payload example
Create and complete a task
Create request
POST /tasks-api/api/v1/tasks
{
"name": "Review Q3 supplier contract",
"description": "Check renewal terms and summarize commercial risks.",
"priority": "high",
"assignedTo": {
"type": "agent",
"id": "agent_legal_01",
"name": "Legal Analyst"
},
"dueDateTime": "2026-08-15T16:00:00Z",
"context": { "supplierId": "sup_204" },
"todos": [
{ "description": "Review renewal and termination clauses", "order": 1 },
{ "description": "Prepare a risk summary", "order": 2 }
]
}
Create response
{
"id": "67a30f1c41b6d2a71f003e99",
"uri": "unago://tasks/67a30f1c41b6d2a71f003e99",
"name": "Review Q3 supplier contract",
"status": "pending",
"priority": "high",
"isBlocked": false,
"createdAt": "2026-08-11T10:00:00Z"
}
Status update
PUT /tasks-api/api/v1/tasks/67a30f1c41b6d2a71f003e99/status
{
"status": "completed",
"result": "Review complete. Two renewal risks require approval."
}
Payload example
Create and trigger a personal automation
Create request
POST /tasks-api/api/v1/automations
{
"name": "Weekday pipeline summary",
"taskDescription": "Summarize pipeline movement and highlight blocked deals.",
"todos": [
"Read the latest CRM changes",
"Group material movement by owner",
"Write an executive summary"
],
"agent": {
"type": "agent",
"id": "agent_sales_01",
"name": "Sales Analyst"
},
"schedule": {
"type": "recurring",
"cronPattern": "0 9 * * 1-5",
"timezone": "Europe/London",
"enabled": true
},
"reuseConversation": true
}
Create response
{
"id": "67a3152d41b6d2a71f004010",
"name": "Weekday pipeline summary",
"status": "active",
"todos": [
"Read the latest CRM changes",
"Group material movement by owner",
"Write an executive summary"
],
"reuseConversation": true,
"runAsUser": false
}
Immediate run request
POST /tasks-api/api/v1/automations/67a3152d41b6d2a71f004010/run
{ "confirmed": true }
Payload example
Upload and move a file
Multipart upload
The file part must be sent last so the service can stream it directly to storage.
curl -X POST "$BASE_URL/storage-api/api/v2/storage/files/upload" \
-H "Authorization: Bearer $TOKEN" \
-F "path=/user-data/reports/q3-review.pdf" \
-F "overwrite=true" \
-F "file=@q3-review.pdf;type=application/pdf"
Upload response
{
"success": true,
"fileId": "fil_85e03",
"path": "/user-data/reports/q3-review.pdf",
"hyperionURI": "unago://files/user-data/reports/q3-review.pdf",
"outputUri": "unago://files/user-data/reports/q3-review.pdf",
"size": 248193,
"checksum": "sha256:7e2d...",
"uploadedAt": "2026-08-11T10:15:00Z",
"scope": "user"
}
Move request
POST /storage-api/api/v2/storage/files/move
{
"source": "/user-data/reports/q3-review.pdf",
"destination": "/company-data/contracts/q3-review.pdf"
}
Error handling
Treat every non-2xx response as a failure
Preserve the status code and safe error details in integration logs. Never log tokens, passwords, uploaded file contents, or private record values.
Validation error
{
"error": "Invalid request body",
"details": {
"field": "status",
"message": "status is required"
}
}
Recommended client handling
const response = await fetch(url, options);
const payload = await response.json();
if (!response.ok) {
throw new Error(payload.error || `HTTP ${response.status}`);
}
return payload;
FAQ
Integration FAQ
Common implementation questions for external platform teams.
Which base URL should my integration use?
Use the HTTPS origin assigned to your environment. Keep it configurable so development, staging, and production can use separate values without code changes.
How should tokens be stored?
Keep tokens in a secure server-side secret store or protected runtime memory. Do not place them in URLs, source code, analytics events, or application logs.
How should list pagination be implemented?
Send limit and offset, retain the returned total where available, and continue only while hasMore is true. Apply a deterministic sort when stable ordering matters.
Which file URI should integrations persist?
Persist the canonical unago://files/... value returned by Storage API. Use the corresponding download or metadata endpoint when the file is needed later.