/users

Admin Funktionen zur Verwaltung von Nutzern.

POST @ /users

Creates a new api user. A user is specified by the tupel {apikey, token, remote-ip}. Every registered user can use /cli-credential resource to create temporary session tokens for clients (independent from IP). If you want to use several IPs from multiple Webserver, you need multiple api users.

URL : /users
Method : Post
HeaderParam
  Admin-Apikey : <your admin-apikey> (BASE64 Encoded)
  Admin-Token : <your admin token> (BASE64 Encoded)
@Consumes : application/json, utf8-encoded
@Produces: application/json, utf8-encoded
Header Parameters admin_apikey / admin_token
These key/tokens are required as HeaderParam BASE64 encoded Admin users are stored in same database table (dvconfigapi.cf_registered_users) and marked by admin flag.

Example Request

HTTP POST to /users with utf-8 encoded body

{
  "apikey_prefix" : "<some human readable api-key prefix for new user>",
  "ip" : "127.0.0.1",
  "endtime" : "2016-03-30",
  "isAdmin" : "false"
}

Arguments

apikey_prefix

Some human readable prefix for generated api_key like name and company. A random token will be added to the human readably prefix. Use this result apikey for your user (see below). If nothing is specified, result will be only the random token.

Rules for key_prefix: - Spaces will be replaced by _ - Allowed characters: 0-9, A-Z, a-z, -_ other chars will be escaped. - Length cut donw <25 Characters

ip
  • IP Version will be detected if v4 or v6.
  • If given IP is not vadil, it will return an error (400, Bad Data).
endtime
  • Timestamp, when access to api will end
  • /cli-credential will check this datetime
  • format: yyyy-[m]m-[d]d hh:mm:ss[.f...]
  • php5.5: recommended to use DateTime->format(“Y-m-d h:i:s”);
  • if timestamp format is not correct, api throws an 400 error and user will not be created
isAdmin
  • optional bool key, if you want to create a new admin

Response

POST Reponse is JSON and will look like:

{
  "apikey" : "Testnutzer_29hd5obij00g1d83coumkl8gd08",
  "token" : "8sqe006a4stmvkjronbq67iihpc8qp7ob30n53lcedd22784q8vniq2otu88u4vl8bf97gmmf8a",
  "starttime" : "2015-12-31",
  "endtime" : "2016-03-30",
  "IPv4" : "127.0.0.1",
  "IPv6" : "NULL",
  "isAdmin" : false,
  "isDeleted" : false
}

The generated registered user can now use API with apikey and token. Starttime is date of user creation.

For saving key and token, please bw aware:
  • apikey - up to 256 chars
  • token - up to 1024 chars

GET @ /users/{apikey}

Read API user.

URL : /users
Method : GET
HeaderParam
  admin_apikey : <your admin-apikey> (BASE64 Encoded)
  admin_token : <your admin token> (BASE64 Encoded)
PathParam:
  apikey : <key of registered user, that you want to read>
@Consumes : ---
@Produces: application/json, utf8-encoded

Produce same output like POST method.

PUT @ /users/{apikey}

Updates user to “expire date” (endtime). This PUT ressource works just as update, not as create or update. If user was not found, returns a 404.

URL : /users
Method : PUT
HeaderParam
  Admin-Apikey : <your admin-apikey> (BASE64 Encoded)
  Admin-Token : <your admin token> (BASE64 Encoded)
PathParam:
  apikey : <key of registered user, that you want to update>
@Consumes : application/json, utf8-encoded
@Produces: text/plain

Produce same output like POST method.

Request Body:

{
  "endtime" : "<new endtime, format see POST method"
}

Returns true or Error with status code.

DELETE @ /users/{apikey}

Deletes user (set delete flag to 1). Returns a 404 if user was not found.

URL : /users
Method : DELETE
HeaderParam
  Admin-Apikey : <your admin-apikey> (BASE64 Encoded)
  Admin-Token : <your admin token> (BASE64 Encoded)
PathParam:
  apikey : <key of registered user, that you want to update>
@Consumes : application/json, utf8-encoded
@Produces: text/plain

Returns true, if user was deleted, or Error with status code.