Skip to main content
Documentation & User Guides | Fotoware

User authentication with the Archive Agent API

An Archive Agent client must authenticate itself as a FotoWeb user to access archives in FotoWeb. There are several ways to accomplish this.

Method 1: Passing credentials in the query string

This authentication method is stateless and does not require storing persistent information on the client side. However, user credentials must be sent with every request, which requires the client application to always know the user's password.

The following query string can be added to every request to Archive Agent for authentication:


Note that the credentials are sent in plain text. It is, therefore, highly recommended to use an encrypted connection (HTTPS).

Method 2: One-time authentication with credentials

This authentication method requires using the user's credentials (username and password) only once. An initial request generates a device token, which can be stored by the client application and sent with every subsequent request to Archive Agent.

The device token is requested as follows:

POST /fotoweb/cmdrequest/Login.fwx
Content-Type: application/x-www-form-urlencoded


Note that the user credentials (the last line) are embedded in the body of the request. However, they are still being sent in plain text. It is, therefore, highly recommended to use an encrypted connection (HTTPS).

The server responds to the request as follows:

200 OK
Set-Cookie: FWSession=token

where token is the device token. It can be sent with every request to Archive Agent to authenticate as the given user by adding the following request header:

Cookie: FWSession=token

Every client application should request one device token per distinct user accessing the Archive Agent API and store it persistently (for example, in a file on disk or a database). A new device token for the same user should be requested only if a request to Archive Agent fails due to an invalid device token.

Device tokens can be revoked for each user by the system administrator.


  • Many HTTP clients automatically handle cookies. When using such an HTTP client in a client application, it is not necessary to manually parse the Set-Cookie header and set the Cookie header on each request. However, when reading the device token from persistent storage, it needs to be added to the cookie list of the HTTP client.
  • Each user can have more than one device token, but there is an upper limit. FotoWeb Desktop and the mobile FotoWeb applications on iOS and Android also use device tokens. If too many device tokens are created for the same user, they have to be revoked by the administrator to allow new device tokens to be created. Therefore, client applications should always reuse device tokens for as long as they are valid and store them on disk or in a database.
  • Despite the name, FWSession is not a session cookie. No session will be listed in the session list in the FotoWeb configuration interface. There is no such thing as a logout request. Device tokens remain valid forever until they are revoked by the administrator.
  • The name of the cookie, FWSession, is for legacy reasons only. Creating a device token does not create a user session. Consequently, no entry appears in the session list in Operations Center. This behavior differs from FotoWeb 7.0, where the above request created a user session and FWSession was used as a session cookie. The name "device token" is because the FotoWeb mobile applications also use device tokens.

Method 3: One-time authentication with login tokens

This authentication method is similar to the previous one, except a login token is used to initially authenticate the user rather than the user name and password. This avoids giving the user's password to the API client.

At first, the API client must create a login token based on the user name and the global encryption secret of the server. This is described in detail in the article about Login Tokens.

The login token must then be passed to the first request as a query string parameter, as follows:


For example:


If authentication with the login token succeeds, then the server sends a device token in the response:

Set-Cookie: FWSession=token

For more information about device tokens, see the description of the previous method, in particular the remarks section.

It is OK (but not recommended) to send a (new) login token with every request. If the client already has a device token, and the device token is sent to the server as an FWSession cookie, the login token is ignored, and the existing device token is used.

This approach does not send any plain text passwords to the server. However, the token can still be stolen and used for authentication within its lifetime. Also, the token does contain the user name in plain text (encoded as base64). Therefore, using a secure connection (HTTPS) is highly recommended.

Which authentication method should be used?

For most scenarios, the third method using login and device tokens is preferred since it does not require giving user passwords to an integration. However, the integration does need the encryption secret of the server and is therefore able to authenticate all users whose user names are known to it. Therefore, the integration has to be fully trusted by the FotoWeb administrator and all users of the FotoWeb system.

The second method can be used if users should be prompted for their password before being allowed to use an application that uses the Archive Agent API. Then, the password entered by the user can be used for authentication. Note that, also with this method, the integration has to be fully trusted by all FotoWeb users and the FotoWeb administrator because it can see plain-text user passwords and (in theory) store them.

The first method has the advantage of being simple and stateless. If an integration only makes one request at a time, it is as good as the second method.

None of these methods are suitable if the integration cannot be fully trusted by the FotoWeb administrator or FotoWeb users.

Validity of image IDs

Some ArchiveAgent methods return image IDs. These IDs may be linked to a certain client (distinguished by its device token, i.e., the value of its FWSession cookie). Within the same client, these IDs are valid permanently. However, administrators can revoke device tokens, invalidating all linked image IDs. Furthermore, different clients cannot exchange image IDs.

To avoid problems, it is best to see image IDs as temporary, and they should only be passed from one request to the next few requests sent by the same client. Image IDs should not be stored in databases or any other persistent storage.