Skip to content

API-Key

Properties of an API-Key.

Name Type Description
id int Unique ID of the key
username string Name of the user to which the token belongs to
api-key string 64 characters long API key
time_offset int Time offset in seconds in comparison to the servers time zone. That value is automatically updated and calculated when you specify the header Client-Date in the request with the API-Key. The value is only valid for 7 days. Afterwards, the default offset calculated from the users time zone is used
alias string "Name" of the API-Key
os string Name of the operating system / Browser on which the API-Key is used
os_version string Version number of the operating system
create_date DateTime Date and time of the creation of the key
valid_until DateTime Expire date of the token
last_login DateTime Time of the last request for API
last_client_version string Version number (like 4.0.3) the client provided with its last API request
version_actuality int States how "up-to date" the last_client_version is compared to the servers version. 4 = up to date, 3 = bugfix version behind, 2 = minor version behind, 1 = major version behind, 0 = no information about the version available
priveledged bool Allow to execute priveledged operations (like authorized by username and password) in a time span of 30 minutes since the last_authorize date
last_authorize DateTime Last time the API-Key was validated with a username and password
socket_conneted DateTime, ro Date since the token is connected to the WebSocket. This value is inaccurate when the same token is connected multiple times to a WebSocket (which is not recommended!). Otherwise, this value is null

Token rights and details

To restrict the actions that a token may perform, it can contain access restrictions for a specific attribute and all entries connected to this.

The following rights are available:

  • all The token can execute all operations for the entry and attribute like creating, updating, deleting und viewing
  • none The attribute is "hidden" for the token and cannot perform any actions for the attribute or entry
  • read The attribute and the entries can only be viewed, but no operation for these are permitted
  • write Only entries for the attribute can be created. Take in mind that the entries in general can only be created and NOT viewed, deleted or updated. Only if the token was the creator of the entry, he is allowed to perform these actions.

To apply these restrictions, a token contains the following fields:

Name Type Description
global_rights string (levels) Global token restrictions for all attributes, for which no specific access restriction was set. Defaulting to all
attribute_details AttributeDetails[], opt Specific rights and details for a single attributes. These settings do overwrite the global_rights. Every attribute can only be specified once. The key to every object is the attributeID

AttributeDeteils

Every AttributeDetails object contains the following fields for a specific attribute.

Name Type Description
attribute_id int ID of the attribute to apply these settings
right string (levels) Specific access restriction applied for the attribute
execution_offset int The exeuction offset in seconds for a single token. The execution of entries will be earlier / later based on this value

Get all API-Keys (GET /api-key)

Details

Get all API-Keys belonging to the user account.

  • If logged in with an api-key, only information about the currently used API-Key can be retrieved
  • If logged in with username and password, or your api-key is priveleged, all API-Keys will be fetched, but they get obfuscated (only the first and last three digits can be obtained)
  • [ If logged in with the socket-key, the API-Keys won't be obfuscated, but he must be logged in with the user credentials ]

Request parameter

Name Type Description
fields[] mixed, optional Fields to included in the response

Response body

[
    {
        "id": 66,
        "username": "ab",
        "api-key": "b9f....b42",
        "time_offset": 0,
        "alias": "115UbuntuGUI",
        "os": "Linux",
        "os_version": "5.18.0-051800rc1-generic",
        "create_date": "2022-06-21T10:41:22",
        "valid_until": "2023-06-22T10:41:22",
        "last_login": "2022-07-01T07:40:40",
        "last_client_version": "4.0.3",
        "priveledged": false,
        "last_authorize": "2023-02-18T19:01:49",
        "global_rights": "all",
        "attribute_details": {}
    },
    {
        "id": 64,
        "username": "ab",
        "api-key": "40c....2ae",
        "time_offset": 0,
        "alias": "115UbuntuGUI",
        "os": "Linux",
        "os_version": "5.18.0-051800rc1-generic",
        "create_date": "2022-06-20T14:43:24",
        "valid_until": "2023-06-21T14:43:24",
        "last_login": "2022-06-21T09:59:03",
        "last_client_version": null,
        "priveledged": true,
        "last_authorize": "2023-02-19T10:22:49",
        "global_rights": "read",
        "attribute_details": {
        "2": {
            "attribute_id": 2,
            "right": "none",
            "execution_offset": 200
        }
    }
]
Response codes
  • 200 The api-keys was returned successfully
  • 204 No API-Keys exists
  • 401 Authentication failed
  • 404 The given api-key was not found

Get a single API-Key (GET /api-key/{api-key|id} or PROPFIND /api-key)

Details

Get a single API-Key.

  • If logged in with an api-key, only information about the currently used API-Key can be retrieved
  • If logged in with username and password, or your api-key is priveleged, all API-Keys will be fetched, but they get obfuscated (only the first and last three digits can be obtained)
  • [ If logged in with the socket-key, the API-Keys won't be obfuscated, but he must be logged in with the user credentials ]

Request parameter

Name Type Description
fields[] mixed, optional Fields to included in the response
cookie boolean, optional A cookie with the requested API-Key will be returned to the client. For that you have to be logged in with this API-Key
cookie-validity int, optional Validity in hours of the cookie
userInfos bool, optional Also include the user details of the token in the response. An additional property user is available which contains the User object

Request body

If you use the PROPFIND method of the endpoint, you can specifiy the token in the body as a property named x-api-key.

Info

This should always be used insted of the GET endpoint for security reasons because request parmaeters may be logged by the client or webserver.

Response body

{
    "id": 67,
    "username": "ab",
    "api-key": "ee2....cc1",
    "time_offset": 0,
    "alias": null,
    "os": null,
    "os_version": null,
    "create_date": "2022-06-24T20:48:19",
    "valid_until": "2023-06-25T20:48:19",
    "last_login": "2022-07-01T17:08:49",
    "last_client_version": null,
    "priveledged": false,
    "last_authorize": "2023-02-19T10:22:49",
    "global_rights": "none",
    "attribute_details": {
        "2": {
            "attribute_id": 2,
            "right": "none",
            "execution_offset": 0
        },
        "3": {
            "attribute_id": 3,
            "right": "all",
            "execution_offset": -150
        }
    }
}

Response header

If you requested to create a cookie and are also authenticated with the correct token, you will receive a cookie named rpdb_apiKey in the headers (Set-Cookie):

rpdb_apiKey=edd82f90f7052a68d75f52ef19d83edb0a839c697e2cc9baf7ac4265f031a748; expires=Thu, 08-Feb-2024 18:15:06 GMT; Max-Age=31622400; path=/api; secure; HttpOnly
Response codes
  • 200 The api-key was returned successfully
  • 401 Authentication failed
  • 404 The given api-key was not found

Create API-Key (POST /api-key)

Details

Creates a new api-key for the currently authorized user with a default validity of one year.

Request body

You can provide the following fields for a better identification of the API key.

  • alias
  • os and os_version
  • priveledged
  • global_rights and attribute_details

These two fields can also be specified.

Name Type Description
validity int, optional How long the API-Key should be valid in hours. Defaults are 365 Days
cookie boolean, optional A cookie with the requested API-Key will be returned to the client

Example:

{
    "alias": "This is a simple test",
    "os": "Linux",
    "os_version": "Linux 6.1.0 Generic (Ubuntu)",
    "global_rights": "none",
    "validity": 6,
    "attribute_details": {
        "3": {
            "attribute_id": 3,
            "right": "all",
            "execution_offset": 0
        },
        "thisDoesntMatter": {
            "attribute_id": 4,
            "right": "read",
            "execution_offset": 0
        }
    }
}

Response body

The created x-api-key.

{
    "id": 55,
    "username": "ab",
    "api-key": "37fb93c7c4ddf2add9da2ae82f0c59458b149fb46108690c06ac665a4836f9df",
    "alias": "PHP Server",
    "os": "Linux",
    "os_version": "5.18.0-051800rc1-generic",
    "create_date": "2022-06-20T10:29:53",
    "valid_until": "2022-06-20T20:29:53",
    "last_login": "2022-06-20T10:29:53",
    "priveledged": false,
    "last_authorize": "2023-02-19T10:22:49",
    "global_rights": "none",
    "attribute_details": {
        "2": {
            "attribute_id": 2,
            "right": "none",
            "execution_offset": 0
        },
        "3": {
            "attribute_id": 3,
            "right": "all",
            "execution_offset": 0
        }
    },
    "message": {
        "client": "Dein Zugriffs-Token wurde erfolgreich erstellt"
    }
}

Response header

If you requested to create a cookie you will receive a cookie named rpdb_apiKey in the headers (Set-Cookie):

rpdb_apiKey=edd82f90f7052a68d75f52ef19d83edb0a839c697e2cc9baf7ac4265f031a748; expires=Thu, 08-Feb-2024 18:15:06 GMT; Max-Age=31622400; path=/api; secure; HttpOnly

Response codes

  • 201 the api-key was created
  • 401 Authentication failed

Delete all API-Keys (DELETE /api-key)

Details

This action deletes all api-keys from the user.
Note that you have to be authorized by username and password.

Response codes

  • 200 all api-keys were deleted
  • 401 Authentication failed

Delete a single API-Key (DELETE /api-key/{api-key|id})

Details

Deletes a single api-key.

Request body

If you do not want to specifiy the API-Key as a URL parameter for security reasons, you can also provide it via the body or a cookie. For that you have to specify -1 as a "pseudo ID" in the URL.

Name Type Description
x-api-key int or string, optional ID or token value to delete
cookie boolean, optional Empty cookie will be returned to overwrite any existing cookies

Response Codes

  • 200 api-key was deleted
  • 400 Invalid values for fields supplied
  • 401 Authentication failed
  • 403 Only the own token can be deleted without an authentication
  • 404 The given api-key was not found

Response header

If you requested a cookie, you will receive it so that it will overwrite (delete) any existing ones:

rpdb_apiKey=deleted; expires=Thu, 01-Jan-1970 00:00:01 GMT; Max-Age=0; path=/api; secure; HttpOnly

Update API-Key (PUT /api-key/{api-key|id})

Details

Updates an API-Key.

Request parameters

Name Type Description
{api-key|id} int or string The unique ID of the key or the token itself. Specifiy -1 to use the token from a cookie or the body

Request body

See properties for values and Create token for an example.

Response

See action Get single token for a response body.

Response codes

  • 200 Token updated
  • 201 Token was not updated because nothing was changed
  • 400 Invalid fields supplied
  • 401 Authentication failed
  • 404 The token was not found

Patch API-Key (PATCH /api-key/{api-key|id})

Details

Patches a token.

See Update token for more information. At least one property of the token has to be specified. If you specify attribute rights, all attribute rights will be replaced by the new one.

Logout from API-Key (POST /api-key/logout)

Details

Deletes a previous set cookie for an API-Key by overwriting it with an empty cookie. The api-key won't be deleted on the application side.

Response header

Expired cookie to overwrite (delete) any existing ones:

rpdb_apiKey=deleted; expires=Thu, 01-Jan-1970 00:00:01 GMT; Max-Age=0; path=/api; secure; HttpOnly

Authorize API-Key (POST /api-key/{api-key|id}/authorize)

Details

Authorizes an API-Key by logging in with username and password. With that, you can use it for priveledged operations within the next 30 minuts.

If you do not want to specifiy the API-Key as a URL Parameter, you can also use your currently authenticated token by specifiying -1 as the ID of the token.

Response

See action Get single token for a response body.

Response Codes

  • 200 api-key was reauthorized
  • 401 Authentication failed
  • 404 The given api-key was not found

Register a single Entry as executed (POST /api-key/execution/{id})

Details

Marks an entry as executed for attributes with the type EA.

Request parameters

Name Type Description
{id} int The ID of the entry to register

Response codes

  • 201 Entry was registered
  • 400 Invalid values for fields supplied
  • 401 Authentication failed

Register entries as executed (POST /api-key/execution)

Details

Marks multiple entries as executed for attributes with the type EA.

Request parameters

Name Type Description
bulk[] int[] List of entries to register

Response body (multi response)

The following statuses can occur:

  • registered Entry was registered as executed
  • exists Entry was already registered as executed
  • error An entry belonging to an attribute with the flag execute always was not found

See the below example for a response with multiple response codes:

{
    "overview": {
        "successful": 1,
        "errors": 0,
        "exists": 1
    },
    "response": [
        {
            "status": "exists",
            "code": 400,
            "error": {
                "message": "Die angegegebene ID wurde bereits als ausgeführt registriert",
                "id": "ENTRY_EA_EXIST"
            }
        },
        {
            "status": "registered",
            "code": 200,
            "data": true
        }, // etc ...
    ],
    "message": {
        "client": "Alle Einträge wurden erfolgreich registriert (2)"
    }
}

Response codes

  • 200 Entries registered as executed
  • 207 Multiple response codes → see the response body for more information
  • 400 No entry was registered
  • 401 Authentication failed