API (v2) Authentication

AUTH (localhost only)

AUTH is issed with a valid username and password. If successful, it returns a sessionId that can be used for AUTHKEY authentication instead of the password. The sessionId is valid until the session expires for old age and inactivity or until an ENDKEY is sent.

curl -sk -X POST https://127.0.0.1:9092/v2/cce -d '{ "cmd": "AUTH", "user": "admin", "password": "PASSWORD" }' | jq

Response (success):

{
    "status": 201,
    "message": "GOODBYE",
    "data": {
        "sessionid": "tK46aZ885HA1QxEiti1dlq.....VpQM3cfavn1yxfF8vFEBeoH3"
    }
}

Response (fail):

{
    "status": 401,
    "message": "GOODBYE",
    "data": {
        "errors": [
            {
                "code": 401,
                "message": "FAIL"
            }
        ]
    }
}

AUTHKEY (localhost only)

Allows you to authenticate with a username of a valid user and an existing unexpired sessionId (instead of using the password). The so initiated session is valid until it expires due to inactivity or when an ENDKEY is sent.

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{ "cmd": "AUTHKEY", "user": "admin", "sessionid": "SESSIONID" }' | jq

Response (success):

{
    "status": 201,
    "message": "GOODBYE",
    "data": {
        "sessionid": "tK46aZ885HA1QxEiti1dlq.....VpQM3cfavn1yxfF8vFEBeoH3"
    }
}

Response (fail):

{
    "status": 401,
    "message": "GOODBYE",
    "data": {
        "errors": [
            {
                "code": 401,
                "message": "FAIL"
            }
        ]
    }
}

LOGIN (remote only):

The LOGIN authentication method only works from remote and for IPs that are allowed to access and use the API. A valid Client-Secret must be used and that Client-Secret must be associated with the originating whitelisted IP address from which the API call originates. Successful authentication via LOGIN grants 'serverAdministrator' access to the API. It returns a Token and the time and date until which that token is valid. The returned token can be used in additional transactions and must be supplied in all remote transactions. The token expires at the end of its validity or when an ENDKEY is sent.

curl -sk -X POST https://API_IP:9092/v2/cce -H "Content-Type: application/json" -H "X-Client-Secret: YOUR-CLIENT-SECRET" -d '{"cmd": "LOGIN"}' | jq

Response (success):

{
    "status": 201,
    "message": "TOKEN ISSUED",
    "data": {
        "expires": "2025-05-17T23:49:24-05:00",
        "token": "IaKCHhrATt7rp8enHNKC5jyuY8AripmELHXXVheAAKj5CfQD30SKAAAowHHLpSVW"
    }
}

Response (fail):

Unauthorized: invalid client secret

WHOAMI (local usage):

The WHOAMI command (if successful) returns the CODB Object ID (OID) of the logged in User. Or "-1" on failure. Username and sessionId must be supplied.

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "WHOAMI",
  "user": "admin",
  "sessionId": "SESSION-ID"
}' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "oid": "6"
  }
}

Response (fail):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "errors": [
      {
        "code": 401,
        "message": "FAIL"
      }
    ],
    "oid": "-1"
  }
}

WHOAMI (remote usage):

For remote usage the WHOAMI command must be used with the Client-Secret AND a valid unexpired token that was issued during LOGIN. If successful it returns the CODB Object ID (OID) of the logged in User. 

curl -sk -X POST https://API_IP:9092/v2/cce   
  -H "Content-Type: application/json"   
  -H "X-Client-Secret: CLIENT-SECRET"   
  -d '{
        "cmd": "WHOAMI", 
        "token": "IaKCHhrATt7rp8enHNKC5jyuY8AripmELHXXVheAAKj5CfQD30SKAAAowHHLpSVW"
      }' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "oid": "60"
  }
}

Response (fail):

Invalid or expired token

BYE (local usage):

Ends the connection to the API, but lets the sessionId remain valid.

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "BYE",
  "user": "admin",
  "sessionId": "P07BbypRtaseyjXxSdhIGliNWIUcEhQi6LJ77WMqW2vibgDRkKpQWwtG4bIwhmE"
}' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "DATA": {}
  }
}<br />

BYE (remote usage):

Ends the connection to the API, but lets the token remain valid.

curl -sk -X POST https://API-IP:9092/v2/cce   
  -H "Content-Type: application/json"   
  -H "X-Client-Secret: CLIENT-SECRET"   
  -d '{"cmd": "BYE"}' | jq

Response (success):

{
  "status": 202,
  "message": "GOODBYE",
  "data": {
    "DATA": {}
  }
}<br />

ENDKEY (local usage):

Ends the connection to the API and expires the current sessionId.

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "BYE",
  "user": "admin",
  "sessionId": "P07BbypRtaseyjXxSdhIGliNWIUcEhQi6LJ77WMqW2vibgDRkKpQWwtG4bIwhmE"
}' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "DATA": {}
  }
}

ENDKEY (remote usage):

Ends the connection to the API and expires the current token.

curl -sk -X POST https://API_IP:9092/v2/cce 
  -H "Content-Type: application/json" 
  -H "X-Client-Secret: CLIENT-SECRET" 
  -d '{ "cmd": "ENDKEY", "token": "TOKEN" }' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "DATA": {}
  }
}