User authentication with the Archive Agent API

Method 1: Passing Credentials in the Query String

This authentication method is stateless and does not require storing any persistent information on the client side. However, user credentials have to be sent with every request, which requires that the client application always knows 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 the use of 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 that is accessing the Archive Agent API and store it persistently (for example, in a file on disk or in 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 the necessity of 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, then 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 tokens and device tokens is the preferred one, 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 which uses the Archive Agent API. Then the password entered by the user can be used to authentication. Note that, also with this method, the integration has to be fully trusted by all FotoWeb users and by 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, then 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, device tokens can be revoked by administrators, which also makes all linked image IDs invalid. 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.