Skip to main content

 

Documentation & User Guides | FotoWare

API Authentication

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. For more information, see the FotoWeb Licensing topic.

Authenticated access requires that one of the available authentication methods are 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

This type of authentication gives the API client full access to all resources which 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-ends applications. The application needs a token that has 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

Please 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.

User Server-to-Server API Authentication

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-ends 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 is provided by the server when a token is requested.

Before the expiration time, the API client can assume that the token is valid. It is possible that the token is revoked by an administrator or user. However, this should be treated by the API client 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 which 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 1 week and refresh it every day when the application starts

Security Considerations

In order 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 method of authentication 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
  • Was this article helpful?