{ "openapi": "3.0.0", "info": { "title": "ZeyOS Legacy Authentication API", "termsOfService": "https://www.zeyos.com/termsofservice", "contact": { "name": "ZeyOS GmbH & Co. KG", "url": "https://www.zeyos.com", "email": "info@zeyos.com" }, "version": "v1" }, "externalDocs": { "description": "ZeyOS Developer Center", "url": "https://developers.zeyos.com" }, "servers": [ { "url": "https://cloud.zeyos.com/{INSTANCE}/auth/v1", "description": "ZeyOS Cloud", "variables": { "INSTANCE": { "default": "demo" } } } ], "tags": [ { "name": "general", "description": "General Authentication" }, { "name": "token", "description": "Token Authentication" } ], "components": { "securitySchemes": { "token": { "type": "http", "scheme": "bearer", "description": "HTTP Bearer Authentication ([RFC 6750](https://tools.ietf.org/html/rfc6750))" }, "session": { "type": "apiKey", "name": "ZEYOSID", "in": "cookie", "description": "Session Cookie Authentication ([RFC 6265](https://tools.ietf.org/html/rfc6265))" } }, "schemas": { "login": { "type": "object", "required": [ "name", "password", "identifier" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Username or e-mail address", "example": "john.doe" }, "password": { "type": "string", "format": "password", "description": "Password", "example": "**********" }, "identifier": { "type": "string", "pattern": "^[a-zA-Z0-9_.:-]+$", "description": "Client's persistent universally unique identifier (e.g. device ID or MAC address)", "example": "95418037-cd82-4ab2-992a-e01370865286" }, "appsecret": { "type": "string", "format": "password", "description": "Application's API secret key", "example": "519d6241f455abbe71d93e0de58083534473a65a" }, "otp": { "type": "string", "format": "password", "description": "OTP authentication code for 2FA (optional)", "example": "123456" }, "expdate": { "type": "integer", "format": "int64", "nullable": true, "default": null, "description": "Token expiry date and time as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) (optional, defaults to 100 days from now)", "example": 872838840 } } } }, "responses": { "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "description": "Preferred authentication scheme ([RFC 7235](https://tools.ietf.org/html/rfc7235#section-4.1))", "schema": { "type": "string", "example": "Bearer realm=\"{INSTANCE}\" error=\"invalid_token\"" } } }, "content": { "text/plain": { "schema": { "type": "string", "example": "Unauthorized: Invalid bearer token" } } } }, "500": { "description": "Runtime Error (Internal Server Error)", "content": { "text/plain": { "schema": { "type": "string", "example": "I am afraid I can't do that Dave!" } } } } } }, "paths": { "/": { "get": { "tags": [ "general" ], "summary": "Get User info", "description": "Authenticate with header-supplied credentials and return user info.", "operationId": "getUserInfo", "deprecated": true, "security": [ { "token": [] }, { "session": [] } ], "parameters": [ { "name": "access", "in": "query", "description": "Return user access info (`admin`, `nopublic`, `apionly`, `groups` and `permissions`)", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } }, { "name": "settings", "in": "query", "description": "Return user settings (`settings`)", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Successful Authentication (OK)", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth": { "properties": { "user": { "type": "integer", "format": "int32", "example": 1 }, "application": { "type": "integer", "format": "int32", "nullable": true, "example": 6 }, "lang": { "type": "string", "enum": [ "de_DE", "en_US", "es_ES" ], "example": "en_US" } } }, "user": { "type": "integer", "format": "int32", "description": "User ID", "example": 1 }, "contact": { "type": "integer", "format": "int32", "nullable": true, "description": "User's contact ID", "example": null }, "name": { "type": "string", "minLength": 1, "description": "Username", "example": "john.doe" }, "email": { "type": "string", "format": "email", "minLength": 1, "description": "User's system e-mail address", "example": "john.doe@company.com" }, "admin": { "type": "boolean", "description": "User is an administrator", "example": true }, "nopublic": { "type": "boolean", "description": "User has no access to public data", "example": false }, "apionly": { "type": "boolean", "description": "User is restricted to API access, no regular login", "example": false }, "groups": { "type": "object", "description": "User's group IDs and respective writabilities", "example": { "1": true, "7": false, "13": true } }, "permissions": { "type": "object", "description": "User's permissions and respective writabilities", "example": { "billing": false, "inventory": false, "messages": true, "notes": true, "opportunities": false, "tasks": true } }, "settings": { "type": "object", "description": "User's personal settings" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "500": { "$ref": "#/components/responses/500" } } }, "head": { "tags": [ "general" ], "summary": "Verify credentials", "description": "Authenticate with header-supplied credentials, but do not return any user info.", "operationId": "verify", "deprecated": true, "security": [ { "token": [] }, { "session": [] } ], "responses": { "204": { "description": "Successful Authentication (No Content)" }, "401": { "$ref": "#/components/responses/401" }, "500": { "$ref": "#/components/responses/500" } } } }, "/login": { "post": { "tags": [ "token" ], "summary": "Login", "description": "Login with specified credentials and return a new auto-generated, cryptographically secure and persistent bearer token for subsequent requests' authentication. Use **`GET /logout`** to eventually logout and invalidate that token.", "operationId": "login", "deprecated": true, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/login" } }, "application/json": { "schema": { "$ref": "#/components/schemas/login" } } } }, "responses": { "200": { "description": "Successful Login (OK)", "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "application", "token", "identifier", "expdate" ], "properties": { "user": { "type": "integer", "format": "int32", "description": "User ID`", "example": 6 }, "application": { "type": "integer", "format": "int32", "nullable": true, "description": "Application ID`", "example": 6 }, "token": { "type": "string", "format": "password", "pattern": "^[a-f0-9]{40}$", "description": "Auto-generated bearer token for use in subsequent requests' `Authorization` header", "example": "97c4281ea528ef02ba573fffce2fa80a3a8414b7" }, "identifier": { "type": "string", "pattern": "^[a-zA-Z0-9_.:-]+$", "description": "Client's persistent universally unique identifier (e.g. device ID or MAC address)", "example": "95418037-cd82-4ab2-992a-e01370865286" }, "expdate": { "type": "integer", "format": "int64", "description": "Expiry date and time as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time)", "example": 872838840 } } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Unauthorized: Invalid credentials" } } } }, "500": { "$ref": "#/components/responses/500" } } } }, "/logout": { "get": { "tags": [ "token" ], "summary": "Logout", "description": "Logout and invalidate token. Any subsequent request that uses that token will fail to authenticate.", "operationId": "logout", "deprecated": true, "security": [ { "token": [] } ], "responses": { "204": { "description": "Successful Logout (No Content)" }, "401": { "$ref": "#/components/responses/401" }, "500": { "$ref": "#/components/responses/500" } } } } } }