Table of Contents
API Authentication for non-interactive clients
02. April 2025
Table of Contents
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.
Metadata updates using server-to-server API authentication
Server-to-server API integrations can update all metadata fields for which the API flag is set in the metadata view of an archive. These fields may be configured to be not editable or not viewable by regular users while still allowing updates using server-to-server API integrations. Only fields that are part of the metadata view can be updated.
User Licensing rules for Server-to-server Authentication
While Server-to-Server API Authentication does not involve user impersonation, you need user access licenses for FotoWeb to match the number of users actually using the integration. This is also clearly outlined in the Fotoware End User License Agreement (EULA), which states:
"Only users with a valid license for FotoWeb or another product with a Client Access License may access the APIs directly or indirectly (through a third-party product or service you develop)."
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
Important: Impersonation of the Fotoware site owner cannot be done with FWAPIToken.
This is for security reasons, to prevent impersonation of the site owner by a user who is not actually the site owner but does have permissions to manage users and security. Allowing impersonation of the site owner would be a security risk, as that user has special privileges.
If you need to allow API authentication for the site owner, please use OAuth, or migrate your existing integration to use OAuth.
Learn more: OAuth 2.0 in FotoWeb
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.
Security Considerations
To acquire a user API key, an API client must first have the full API key. The API client is, therefore, able to authenticate any user on the FotoWeb site. It requires neither the approval of an administrator nor the consent of the user being impersonated. Therefore, this method of authentication cannot be used to build certain integrations, such as mobile apps, where the full API key would have to be stored in a place that is not secure, such as a user's phone.
This authentication method is still suitable for implementing the back-end of an application, even a mobile app. If the back-end can ensure that users authenticate themselves in another way (e.g., by entering a username and a password), then the back-end can use server-to-server authentication to make FotoWeb API requests on the user's behalf. The full API key would have to be stored in the back-end only, which must be fully trusted by the FotoWeb administrator.
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