This is a development version of the documentation. Content may change without notice.
Voke Documentation
ReferenceREST API

Auth

Authentication endpoints

Change current user password

POST
/api/v1/auth/change-password

Request Body

application/json

currentPassword*string
Length1 <= length
newPassword*string
Length12 <= length <= 256

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/change-password" \  -H "Content-Type: application/json" \  -d '{    "currentPassword": "string",    "newPassword": "stringstring"  }'
{
  "message": "string"
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Validation error or new == current",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Current password incorrect or unauthenticated",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Confirm intent to accept an invitation — issues a 15m cookie gating registration

GET
/api/v1/auth/confirm-accept

Query Parameters

token*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/v1/auth/confirm-accept?token=string"
{
  "message": "Invitation confirmed. Please complete registration.",
  "redirectPath": "/auth/complete-invite"
}
{
  "code": "INVITATION_TOKEN_MISSING",
  "details": {},
  "error": "Bad Request",
  "message": "Missing token",
  "statusCode": 400
}
{
  "code": "INVITATION_EXPIRED",
  "details": {},
  "error": "Forbidden",
  "message": "Invitation expired",
  "statusCode": 400
}
{
  "code": "INVITATION_NOT_FOUND",
  "details": {},
  "error": "Not Found",
  "message": "Invitation not found",
  "statusCode": 400
}
{
  "code": "INVITATION_ALREADY_ACCEPTED",
  "details": {},
  "error": "Conflict",
  "message": "Already accepted",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Update default organization for the current user

PATCH
/api/v1/auth/default-org

Request Body

application/json

organizationId*string

Organization UUID to set as default

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://loading/api/v1/auth/default-org" \  -H "Content-Type: application/json" \  -d '{    "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9"  }'
{
  "user": {
    "currentOrganization": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "role": "ORG_ADMIN",
      "slug": "string"
    },
    "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
    "email": "string",
    "featureFlags": {
      "vokeEsmEnabled": true
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isSuperAdmin": true,
    "name": "string",
    "organizations": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "role": "ORG_ADMIN",
        "slug": "string"
      }
    ],
    "role": "ADMIN"
  }
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Invalid request body",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Not authenticated",
  "statusCode": 400
}
{
  "code": "ORG_MEMBERSHIP_REQUIRED",
  "details": {},
  "error": "Forbidden",
  "message": "Not a member of the organization",
  "statusCode": 400
}
{
  "code": "ORGANIZATION_NOT_FOUND",
  "details": {},
  "error": "Not Found",
  "message": "Organization not found (SuperAdmin targeting a non-existent org)",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Confirm a pending email change

POST
/api/v1/auth/email/confirm

Request Body

application/json

token*string
Length64 <= length <= 64

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/email/confirm" \  -H "Content-Type: application/json" \  -d '{    "token": "stringstringstringstringstringstringstringstringstringstringstri"  }'
{
  "message": "string"
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Token invalid, expired, or no change pending",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Login with email and password

POST
/api/v1/auth/login

Request Body

application/json

email*string

User email address

Formatemail
password*string

User password

Length8 <= length <= 72

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/login" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com",    "password": "stringst"  }'
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "currentOrganization": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "role": "ORG_ADMIN",
      "slug": "string"
    },
    "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
    "email": "string",
    "featureFlags": {
      "vokeEsmEnabled": true
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isSuperAdmin": true,
    "name": "string",
    "organizations": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "role": "ORG_ADMIN",
        "slug": "string"
      }
    ],
    "role": "ADMIN"
  }
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Validation error",
  "statusCode": 400
}
{
  "code": "INVALID_CREDENTIALS",
  "details": {},
  "error": "Unauthorized",
  "message": "Invalid credentials",
  "statusCode": 400
}
{
  "code": "ACCOUNT_LOCKED",
  "details": {},
  "error": "Forbidden",
  "message": "Account temporarily locked",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}
POST
/api/v1/auth/logout

Response Body

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/logout"
{
  "message": "string"
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Log out of every session (bumps tokenVersion and revokes all refresh)

POST
/api/v1/auth/logout-all

Response Body

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/logout-all"
{
  "message": "string"
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Get current authenticated user with organizations

GET
/api/v1/auth/me

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/v1/auth/me"
{
  "user": {
    "currentOrganization": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "role": "ORG_ADMIN",
      "slug": "string"
    },
    "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
    "email": "string",
    "featureFlags": {
      "vokeEsmEnabled": true
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isSuperAdmin": true,
    "name": "string",
    "organizations": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "role": "ORG_ADMIN",
        "slug": "string"
      }
    ],
    "role": "ADMIN"
  }
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Not authenticated",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Update current user profile (name and/or initiate email change)

PATCH
/api/v1/auth/me

Request Body

application/json

currentPassword?string

Current password — required only when changing email.

Length1 <= length <= 200
email?string
Formatemail
name?string
Length1 <= length <= 120

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://loading/api/v1/auth/me" \  -H "Content-Type: application/json" \  -d '{}'
{
  "user": {
    "currentOrganization": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "role": "ORG_ADMIN",
      "slug": "string"
    },
    "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
    "email": "string",
    "featureFlags": {
      "vokeEsmEnabled": true
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isSuperAdmin": true,
    "name": "string",
    "organizations": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "role": "ORG_ADMIN",
        "slug": "string"
      }
    ],
    "role": "ADMIN"
  }
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Validation error",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Not authenticated, or currentPassword missing/incorrect on email change",
  "statusCode": 400
}
{
  "code": "EMAIL_ALREADY_REGISTERED",
  "details": {},
  "error": "Conflict",
  "message": "Email already registered",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Rotate refresh session and mint a new access token

POST
/api/v1/auth/refresh

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/refresh"
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "currentOrganization": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "role": "ORG_ADMIN",
      "slug": "string"
    },
    "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
    "email": "string",
    "featureFlags": {
      "vokeEsmEnabled": true
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isSuperAdmin": true,
    "name": "string",
    "organizations": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "role": "ORG_ADMIN",
        "slug": "string"
      }
    ],
    "role": "ADMIN"
  }
}
{
  "code": "REFRESH_TOKEN_INVALID",
  "details": {},
  "error": "Bad Request",
  "message": "Refresh cookie missing or malformed",
  "statusCode": 400
}
{
  "code": "REFRESH_TOKEN_INVALID",
  "details": {},
  "error": "Unauthorized",
  "message": "Refresh invalid, expired, or revoked",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Create a new user (SuperAdmin only)

POST
/api/v1/auth/register

Request Body

application/json

email*string

User email address

Formatemail
name*string

User display name

Length2 <= length <= 100
password*string

User password (uppercase, lowercase, digit, and special character required)

Match/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?])/
Length8 <= length <= 72

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/register" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com",    "name": "string",    "password": "stringst"  }'
{
  "user": {
    "email": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "role": "ADMIN"
  }
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Validation error",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "SUPER_ADMIN_REQUIRED",
  "details": {},
  "error": "Forbidden",
  "message": "SuperAdmin access required",
  "statusCode": 400
}
{
  "code": "EMAIL_ALREADY_REGISTERED",
  "details": {},
  "error": "Conflict",
  "message": "Email already registered",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Register via invitation token

POST
/api/v1/auth/register/invite

Request Body

application/json

name*string

User display name

Length2 <= length <= 100
password*string

User password

Match/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?])/
Length8 <= length <= 72
token*string

Invitation token — 64 lowercase hex characters (see InvitationsService.create)

Match/^[a-f0-9]{64}$/
Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/auth/register/invite" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "password": "stringst",    "token": "string"  }'
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "currentOrganization": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "role": "ORG_ADMIN",
      "slug": "string"
    },
    "defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
    "email": "string",
    "featureFlags": {
      "vokeEsmEnabled": true
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isSuperAdmin": true,
    "name": "string",
    "organizations": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "role": "ORG_ADMIN",
        "slug": "string"
      }
    ],
    "role": "ADMIN"
  }
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Validation error",
  "statusCode": 400
}
{
  "code": "INVITATION_CONFIRMATION_REQUIRED",
  "details": {},
  "error": "Unauthorized",
  "message": "Invitation confirmation required or invalid",
  "statusCode": 400
}
{
  "code": "INVITATION_EXPIRED",
  "details": {},
  "error": "Forbidden",
  "message": "Invitation expired",
  "statusCode": 400
}
{
  "code": "INVITATION_NOT_FOUND",
  "details": {},
  "error": "Not Found",
  "message": "Invalid or expired invitation",
  "statusCode": 400
}
{
  "code": "EMAIL_ALREADY_REGISTERED",
  "details": {},
  "error": "Conflict",
  "message": "Email already registered",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

List active sessions for the current user

GET
/api/v1/auth/sessions

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/v1/auth/sessions"
{
  "sessions": [
    {
      "createdAt": "2019-08-24T14:15:22Z",
      "expiresAt": "2019-08-24T14:15:22Z",
      "ip": "string",
      "isCurrent": true,
      "jti": "string",
      "lastUsedAt": "2019-08-24T14:15:22Z",
      "userAgent": "string"
    }
  ]
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Not authenticated",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Revoke a specific session

DELETE
/api/v1/auth/sessions/{jti}

Path Parameters

jti*string

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://loading/api/v1/auth/sessions/string"
{
  "message": "string"
}
{
  "code": "CANNOT_REVOKE_CURRENT_SESSION",
  "details": {},
  "error": "Bad Request",
  "message": "Cannot revoke current session, or session not found",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Not authenticated",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Verify invitation token and return details

GET
/api/v1/auth/verify-invitation

Query Parameters

token*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/v1/auth/verify-invitation?token=string"
{
  "email": "string",
  "inviterName": "string",
  "organizationName": "string",
  "role": "ORG_ADMIN"
}
{
  "code": "INVITATION_TOKEN_MISSING",
  "details": {},
  "error": "Bad Request",
  "message": "Missing invitation token",
  "statusCode": 400
}
{
  "code": "INVITATION_EXPIRED",
  "details": {},
  "error": "Forbidden",
  "message": "Invitation expired or email mismatch",
  "statusCode": 400
}
{
  "code": "INVITATION_NOT_FOUND",
  "details": {},
  "error": "Not Found",
  "message": "Invalid invitation",
  "statusCode": 400
}
{
  "code": "INVITATION_ALREADY_ACCEPTED",
  "details": {},
  "error": "Conflict",
  "message": "Invitation already accepted",
  "statusCode": 400
}
{
  "code": "TOO_MANY_REQUESTS",
  "details": {},
  "error": "Too Many Requests",
  "message": "Too many requests",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Audit

Audit log inspection

Commands

Plant commands