API Authentication for non-interactive clients

Legacy note

This document describes a legacy authentication method.

Note: API Key Authentication is deprecated and will be set to End of Life on January 1st, 2025.

If you have implemented custom integrations with FotoWeb, such as CMS integrations, we recommend updating the authentication methods in use to OAuth, which was introduced in FotoWeb FR12 (version 8.0.850). 

Legacy authentication methods, including FWAPIToken, have been deprecated and will be removed in the future.

Eventually, all applications provided by Fotoware will use OAuth 2.0 to connect to FotoWeb.
We encourage migrating existing third-party integrations to OAuth 2.0 for user experience and security improvements.
Non-OAuth authorization mechanisms from older versions of FotoWeb may be deprecated or disabled by default (with options to enable them).

Note: FotoWeb supports OAuth authentication of non-interactive clients, too, and we also recommend using OAuth for these types of integrations instead of the Full server-to-server API authentication described below.

Learn more: OAuth 2.0 in FotoWeb

Authenticated vs. Unauthenticated Access

The API supports authenticated and unauthenticated access.

Unauthenticated access is read-only and only possible on sites where guest access is enabled and licensed. Unauthenticated clients only have access to resources to which guest access has been granted, such as archives where "Everyone" is in the access list. Some editions of FotoWeb do not support guest access. 

Authenticated access requires that one of the available authentication methods be used. These methods are described in this article.

Note: Using authenticated API requests to the FotoWeb server requires an API License for FotoWeb

Full Server-to-server API Authentication

Note: Instead of using this legacy authentication method, we recommend using OAuth for non-interactive applications

This type of authentication gives the API client full access to all resources that are available in the API. Actions are performed on behalf of the built-in Administrator user.

Server-to-server API authentication is suitable for building back-end integrations, such as application servers. It is not recommended for building front-end applications. The application needs a token with full access to all resources and all user data on the FotoWeb site. This token should only be stored in applications that can be fully trusted.

The integration requires the full API key, and its configuration is outlined in a separate topic.

To use this type of authentication, add the following HTTP header to the request:

FWAPIToken: Full API key

 Note: In demonstrations of the API, FWAPITokenis sometimes sent in the query string. This is an unofficial and unsupported feature that must not be used in production code. Please do not attempt this alternative if you are experiencing problems with the API. Please do not use this method when submitting a dump of an API request to a support ticket.

Server-to-Server API Authentication with User Impersonation

This type of authentication gives the API client access to all resources that a particular FotoWeb user has access to and allows the API client to make requests on behalf of that user, such as creating albums.

Server-to-server API authentication is suitable for building back-end integrations, such as application servers. It is not recommended for building front-end applications. See security considerations below.

Server-to-server user API authentication is also suitable in setups where the end user cannot access FotoWeb but only has access to a third-party application which itself accesses FotoWeb. In such a setup, standard API authentication methods such as OAuth (not supported by FotoWeb) would not be possible.

To use this type of authentication, the API client first needs the full API key, as described in Full Server-to-Server API Authentication. Using the full API key, the API client then requests the full API descriptor as follows:

GET /fotoweb/me
FWAPIToken: Full API key
Accept: application/vnd.fotoware.full-api-descriptor+json

Next, the API client requests a user token for the FotoWeb user to impersonate. This is done by sending the following request to the URL which is provided by the tokens attribute of the full API descriptor:

POST full_api_descriptor['tokens']
FWAPIToken: Full API key
Accept: application/vnd.fotoware.api-token-info+json
Content-Type: application/vnd.fotoware.api-token-request+json

{
  "un": username,
  "app": application name,
  "duration": requested token lifetime
}

where un is the username of the user to impersonate, app is a free-form string that identifies the API client and duration is the maximum amount of time for which the token shall be valid, given as a string in ISO8601 format (e.g., "PT60S" for 60 seconds)

The username can be the username of a FotoWeb user or, if directory service integration is enabled, the name of a user in the directory, which can be given as a plain username, "username@domain" or "domain\username". If the user is found in the directory and does not exist in the FotoWeb user database, then the user is automatically imported.

If successful, the server returns the following response:

200 OK
Content-Type: application/vnd.fotoware.api-token-info+json

{
  "token": user API key,
  "expires": actual token expiry time
}

where user API key is the requested token that can be used for authenticating API requests on behalf of the user and expires is the absolute UTC time at which the token will expire, given as a string in ISO8601 format (e.g., "2016-03-31T16:12:00Z").

The returned token can then be used in subsequent API requests by adding the following request header:

FWAPIToken: user API key

Token Expiration

Every token has an expiration time, which the server provides when a token is requested.

Before the expiration time, the API client can assume that the token is valid. The token may be revoked by an administrator or user. However, the API client should treat this as an unexpected error, and it is not recommended to handle this by automatically requesting a new token and retrying the failed operation.

After the expiration time, the API client should request a new token in the usual way, using the admin token for authentication.

It is, therefore, not necessary and not recommended to handle token expiration with every API request. Instead, every application should have a suitable strategy for when to request a new token and what token duration to request based on the application's API usage pattern.

Meaningful strategies for requesting new tokens might be as follows:

• If the application performs a periodic task every hour that takes up to 5 minutes:
  • Request a new token (valid for 10 minutes) every time the task runs
• If the application is a mobile or browser app
  • Request a token that is valid for as long as a user session lasts, then force the user to log in again and request a new token.
• Or request a token valid for one week and refresh it every day when the application starts.

Authentication example using cURL

The following example shows how to use server-to-server authentication when sending a request using cURL:

curl \
  --header "Accept: application/vnd.fotoware.full-api-descriptor+json" \
  --header "FWAPIToken: API key" \
  http://fotoweb.acme.com/fotoweb/me