ZeyOS Authentication API API Reference

The ZeyOS Authentication API allows you to authenticate ZeyOS users.

You may access the ZeyOS Authentication API via https://cloud.zeyos.com/{INSTANCE}/auth/v1/.

Creating an authentication token is the prerequisite to working with the ZeyOS Standard REST API. Check out the Getting Started Guide in the Standard REST API documentation first, it will make your life easier!

The ZeyOS Authentication API may also be extremely useful if you simply want to use ZeyOS as an authentication provider for external applications, e.g. for single sign-on.

Return Values and Error Handling

The ZeyOS Authentication API currently only returns JSON data and an HTTP status code indicating the outcome of a request.

HTTP status code 200 or 201 are used to indicate a successful response, and the result will be a JSON object.

When an error occurs, the HTTP status code will be 400 or greater, and the response will be a text message.

We recommend that you treat any HTTP status code greater than or equal to 400 as an error.

Creating Authentication Tokens

$ curl -i --data 'name=max.power&password=MySecretPwd&identifier=MyDevice' https://cloud.zeyos.com/demo/auth/v1/login
            
            HTTP/2 200
            server: nginx
            date: Thu, 19 Apr 2018 08:56:20 GMT
            content-type: application/json
            cache-control: no-cache
            expires: Fri, 29 Aug 1997 07:14:00 GMT
            access-control-allow-origin: *
            strict-transport-security: max-age=31536000
            
            {"user":2,"application":null,"token":"a749717494cf42aa2fcb7533a950e2a7350d1086","identifier":"MyDevice","expdate":null}
            

In this example, we are simply authenticating a user via name and password (name may refer to username or email).

Tokens are linked to identifiers which should be specific to both the accessing app and device. This allows devices to renew their tokens independently.

You can also see that the HTTP response code for a successful login is 200. If username or password are wrong, the server will return 401. So always check the response code.

Using application-specific Tokens with the ZeyOS Standard REST API

In case you want to use the ZeyOS Standard REST API, you will need to generate an application-specific authentication token.

The first thing you need to do is create an application in ZeyOS. In ZeyOS, go to Enhancements and create a new application:

Create App

Write down the appsecret as it will be displayed only once when creating the application and should be treated like a password.

Note: In case you loose the appsecret, you can go to the application details and regenerate a new appsecret. All existing tokens that have been signed with the old appsecret will remain valid.

The purpose of the appsecret is to sign authentication tokens so that they can be used with the ZeyOS Standard REST API. This gives system administrators control over which applications may actually be allowed to use the ZeyOS Standard REST API. If an application is deactivated or removed, all issued authentication tokens are rendered invalid.

$ curl -i --data 'name=max.power&password=MySecretPwd&identifier=MyDevice&appsecret=ff55c5095a126d66faaa37cd71bc771672c56ec5' https://cloud.zeyos.com/demo/auth/v1/login

Response:

{
  "user": 2,
  "application": 343,
  "token": "a749717494cf42aa2fcb7533a950e2a7350d1086",
  "identifier": "MyDevice",
  "expdate": null
}

And voilà, you have obtained an application-specific authentication token that can now be used with the ZeyOS Standard REST API.

Validate Authentication Token

If you want to check if a authentication token is still valid, you can simply check your current session, for example:

curl -i -X GET -H 'Authorization: Bearer a749717494cf42aa2fcb7533a950e2a7350d1086' https://cloud.zeyos.com/demo/auth/v1/

Using autentication Tokens with custom REST APIs

Besides using the ZeyOS Standard REST API you can also use iXML to create custom REST APIs. In this case, you can decide whether you want to use ZeyOS's token mechanism to authenticate users or if you want to use a static access key (or no authentication at all).

To check wheter the API request includes a valid authentication header, you can simply check if the AUTH variable is set.

Let's say we want to have a custom API called checkout that simply returns the infos about the user:

<?xml version="1.0" encoding="UTF-8"?>
            <!DOCTYPE ixml SYSTEM "https://developers.zeyos.com/schema/ixml.dtd">
            <ixml>
            
            <!-- Check if the user is authorized -->
            <is var="AUTH.user" type="non-valid">
              <header>HTTP/1.1 403 Forbidden</header>
              <exit/>
            </is>
            
            <output>User ID $AUTH.user is authorized!</output>
            
            <!-- Check if the user token has an expiration date -->
            <if value1="$AUTH.expdate" func="!=">
              <output>Expiry date:</output>
            
              <output>
                <date:format format="Y-m-d H:i">$AUTH.expdate</date:format>
              </output>
            </if>
            
            </ixml>
            

Example request:

curl -i -X GET -H 'Authorization: Bearer a749717494cf42aa2fcb7533a950e2a7350d1086' https://cloud.zeyos.com/demo/remotecall/checkauth
API Endpoint
https://cloud.zeyos.com/{INSTANCE}/auth/v1
Terms of Service: https://www.zeyos.com/termsofservice
Contact: info@zeyos.com
Schemes: https
Version: v1

Authentication

basic

HTTP Basic Authentication ( RFC 7617)

scheme
basic
type
basic

session

Session Cookie Authentication ( RFC 6265)

in
cookie
name
ZEYOSID
type
apiKey

token

HTTP Bearer Authentication ( RFC 6750)

scheme
bearer
type
http

general

Get Session Info

GET /

Authenticate with header supplied credentials and return session info.

access
in query
integer 0, 1

Return user access info (admin, nopublic, groups and permissions)

settings
in query
integer 0, 1

Return user settings (settings)

200 OK

Successful Authentication (OK)

type
object
401 Unauthorized

Unauthorized

type
string
500 Internal Server Error

Runtime Error (Internal Server Error)

type
string
Response Content-Types: text/plain
Response Example (200 OK)
{
  "admin": true,
  "contact": "integer (int32)",
  "email": "john.doe@company.com",
  "groups": {
    "1": true,
    "7": false,
    "13": true
  },
  "name": "john.doe",
  "nopublic": false,
  "permissions": {
    "billing": false,
    "inventory": false,
    "messages": true,
    "notes": true,
    "opportunities": false,
    "tasks": true
  },
  "settings": "object",
  "user": 6
}
Response Example (401 Unauthorized)
"Unauthorized: Invalid token for bearer authentication"
Response Headers (401 Unauthorized)
WWW-Authenticate

Preferred authentication scheme ( RFC 7235)

object
Response Example (500 Internal Server Error)
"I am afraid I can't do that Dave!"

Verify Credentials

HEAD /

Authenticate with header supplied credentials, but do not return any session info.

204 No Content

Successful Authentication (No Content)

401 Unauthorized

Unauthorized

type
string
500 Internal Server Error

Runtime Error (Internal Server Error)

type
string
Response Example (401 Unauthorized)
"Unauthorized: Invalid token for bearer authentication"
Response Headers (401 Unauthorized)
WWW-Authenticate

Preferred authentication scheme ( RFC 7235)

object
Response Example (500 Internal Server Error)
"I am afraid I can't do that Dave!"

token

Login (Token)

POST /login

Login with specified credentials and return an auto-generated, cryptographically secure and persistent bearer token for subsequent requests' authentication. Use GET /logout to eventually logout and invalidate that token.

name
in formData
string

Username or e-mail address

password
in formData
string (password)

User password

identifier
in formData
string

Client's persistent universally unique identifier (e.g. device ID or MAC address)

appsecret
in formData
string (password)

Application's API secret key (optional)

otp
in formData
string (password)

OTP validation code for 2FA (optional)

expdate
in formData
integer (int64)

Expiry date and time as a Unix time stamp (optional)

200 OK

Successful Login (OK)

type
object
401 Unauthorized

Unauthorized

type
string
500 Internal Server Error

Runtime Error (Internal Server Error)

type
string
Response Content-Types: application/json
Response Example (200 OK)
{
  "application": "integer (int32)",
  "expdate": 872838840,
  "identifier": "95418037-cd82-4ab2-992a-e01370865286",
  "token": "97c4281ea528ef02ba573fffce2fa80a3a8414b7",
  "user": 6
}
Response Example (401 Unauthorized)
"Unauthorized: Invalid token for bearer authentication"
Response Headers (401 Unauthorized)
WWW-Authenticate

Preferred authentication scheme ( RFC 7235)

object
Response Example (500 Internal Server Error)
"I am afraid I can't do that Dave!"

Logout (Token)

GET /logout

Logout and invalidate token. Any subsequent request that uses that token will fail to authenticate.

204 No Content

Unnecessary Logout (No Content)

205 Reset Content

Successful Logout (Reset Content)

401 Unauthorized

Unauthorized

type
string
500 Internal Server Error

Runtime Error (Internal Server Error)

type
string
Response Example (401 Unauthorized)
"Unauthorized: Invalid token for bearer authentication"
Response Headers (401 Unauthorized)
WWW-Authenticate

Preferred authentication scheme ( RFC 7235)

object
Response Example (500 Internal Server Error)
"I am afraid I can't do that Dave!"

Schema Definitions

login: object

appsecret: string (password)

Application's API secret key (optional)

expdate: integer (int64)

Expiry date and time as a Unix time stamp (optional)

identifier: string

Client's persistent universally unique identifier (e.g. device ID or MAC address)

name: string

Username or e-mail address

otp: string (password)

OTP validation code for 2FA (optional)

password: string (password)

User password

Example
{
  "appsecret": "519d6241f455abbe71d93e0de58083534473a65a",
  "expdate": 872838840,
  "identifier": "95418037-cd82-4ab2-992a-e01370865286",
  "name": "john.doe",
  "otp": "123456",
  "password": "**********"
}