ZeyOS Authentication API API Reference

The ZeyOS authentication API allows you to generate and revoke authentication tokens for ZeyOS users.

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

The ZeyOS Auth API is also extremely useful if you simply want to use ZeyOS as an authentication provider for external applications.

Here are some simple examples using CURL:

$ 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 a via name and password.

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.

App Tokens

In case you want to use the REST API, you will need to generate an application 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 - it will be displayed only once when creating the app and should be treated like a password.

Note: In case you loose the appsecret, you can go to the application opens and generate 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 REST API. This gives system administrators control over which application is actually able to use the 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 token that can now be used with the REST API.

Validation sessions

If you want to check if your 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/
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

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 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

500 Internal Server Error

Runtime Error (Internal Server Error)

type
string
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 persitent 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)

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

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 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

500 Internal Server Error

Runtime Error (Internal Server Error)

type
string
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

password: string (password)

User password

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