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:

?u=USERNAME&p=PASSWORD

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
u=USERNAME&p=PASSWORD

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.

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:

url?lt=token

For example:

/fotoweb/fwbin/fotoweb_isapi.dll/ArchiveAgent/Information?lt=abcdefg==

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.