Authentication

Priostack uses API keys for authentication. Every API request must include a valid API key. Keys are tied to a specific account and carry the credit balance for that account.

Getting Your API Key

Create an account at priostack.com/account — your API key is issued immediately.
Log in to the Console and go to Settings → API Keys.
Copy your API key. You will only see the full key once — store it securely.
New accounts receive 100 free credits automatically, plus 100 more each month.

Important: Treat your API key like a password. Never commit it to source control, never log it, and never share it publicly. If your key is compromised, rotate it immediately from the Console.

Using Your API Key

Include your API key in every request using the X-API-Key header:

curl

curl -X POST https://api.priostack.com/api/v1/process-instances \
  -H "X-API-Key: ps_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"bpmnProcessId": "order-processing", "variables": {"orderId": "123"}}'

Query Parameter (alternative)

If you cannot set headers (e.g., webhook testing), you can pass the key as a query parameter:

curl "https://api.priostack.com/api/v1/process-instances?api_key=ps_live_your_key_here" \
  -X POST -H "Content-Type: application/json" \
  -d '{"bpmnProcessId": "order-processing"}'

Security Note: Avoid using the api_key query parameter in production — URLs may be logged in server access logs, browser history, and HTTP referrer headers.

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("PRIOSTACK_API_KEY")

    body, _ := json.Marshal(map[string]interface{}{
        "bpmnProcessId": "order-processing",
        "variables": map[string]interface{}{
            "orderId": "ORD-001",
            "amount":  149.99,
        },
    })

    req, _ := http.NewRequest("POST",
        "https://api.priostack.com/api/v1/process-instances",
        bytes.NewReader(body))
    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("Status:", resp.Status)
}

Python

import os
import requests

api_key = os.environ["PRIOSTACK_API_KEY"]
base_url = "https://api.priostack.com"

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/api/v1/process-instances",
    headers=headers,
    json={
        "bpmnProcessId": "order-processing",
        "variables": {
            "orderId": "ORD-001",
            "amount": 149.99,
        }
    }
)
print(response.status_code, response.json())

JavaScript (Node.js)

const apiKey = process.env.PRIOSTACK_API_KEY;
const baseUrl = "https://api.priostack.com";

const response = await fetch(`${baseUrl}/api/v1/process-instances`, {
  method: "POST",
  headers: {
    "X-API-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    bpmnProcessId: "order-processing",
    variables: {
      orderId: "ORD-001",
      amount: 149.99,
    },
  }),
});

const data = await response.json();
console.log(data);

Security Best Practices

Practice	Details
Use environment variables	Store your API key in an environment variable (e.g., `PRIOSTACK_API_KEY`), never hardcode it in source files.
Never commit to git	Add `.env` to your `.gitignore`. Use secret scanning tools (e.g., git-secrets, GitHub secret scanning).
Rotate regularly	Rotate your API key quarterly, or immediately if you suspect it has been exposed.
Use HTTPS only	Always use `https://`. HTTP requests are rejected by the Priostack API.
Principle of least privilege	In future: use scoped keys with only the permissions your service needs.

Key Scopes (Roadmap)

Key scoping is planned for a future release. When available, you will be able to create keys restricted to specific operations:

Scope	Permissions
`process:deploy`	Deploy process definitions
`process:start`	Start process instances
`process:read`	Read process instances and incidents
`job:activate`	Activate and complete jobs (for workers)
`admin`	Full access including user management

Verify Your Key

Call GET /api/me to verify your key is valid and check your current credit balance:

curl https://api.priostack.com/api/me \
  -H "X-API-Key: ps_live_your_key_here"

# Response:
{
  "userId": "usr_abc123",
  "email": "you@company.com",
  "credits": 487,
  "plan": "pay-as-you-go",
  "createdAt": "2026-01-15T10:00:00Z"
}