Contact Support
API Reference

Swift Authentication

If you wish to publish certain objects so they can be accessed publicly without requiring authentication, this is something easily done via the container settings. However, by default for operational access (adding/removing objects, labeling, etc.) or just for read access to private objects, authentication is required.

NetFire Cloud Storage uses Swift authentication version 1 (v1, v1.0).

Swift authentication is very simple -- certainly quite less complex than S3, and follows a very similar process to what you may be used to if you have used a REST API that requires token generation.

You will receive three pieces of information (two of which are used in the authentication process) from either NetFire or your company's approved Cloud Storage administrator(s):

  • A username (in the format of TenantID$UserName). This is not used in Swift authentication directly, but may be visible/available in object/container metadata for more human-friendly operations.
  • A Swift username (in the format of TenantID$UserName:KeyID).
  • A Swift Secret Key. As the name implies, this is secret. This must be kept in a safe, secret place.

Throughout this documentation, the examples will use a tenant ID of NetFire, a username of example, and a key ID of demo -- thus our Swift username is NetFire$example:demo.

📘

NetFire will never ask for your secret key!

NetFire staff do not need your Swift Secret Key; please do not provide or offer it and report anyone claiming to be NetFire staff that is asking for your Swift Secret Key.
NetFire staff may, on occasion, ask for the Swift Username of your account to assist in support cases, but we will never ask for your Swift Secret Key. Treat requests for this as illegitimate and not originating from NetFire staff.

🚧

Your Swift username and secret key are different from your S3 credentials!

Your S3 access key and secret key will be entirely different from your Swift username and secret key. Your Swift account is, in essence, a subuser of your S3 user with Swift capabilities/compatibility added onto it.

Generating Tokens

To generate both Auth and Storage tokens, simply perform a GET request against /auth on your endpoint.

📘

This documentation uses the us-east1.swift.netfire.com enpoint in examples.

Thus, the URL that the example uses to authenticate is https://us-east1.swift.netfire.com/auth.

You must provide your Swift Username as the X-Auth-User header, and your Swift Secret Key as the X-Auth-Key header.

You will receive back a response with the following headers:

  • X-Storage-Url contains the canonical base URL for your Swift user on the endpoint you authenticated against
  • X-Auth-Token (and X-Storage-Token; they should contain the same values for historical reasons) contains your authentication token; they look like the following: AUTH_rgwtk140000004e657446697265246578616d706c653a64656d6fa849355906b70f81d6401965ded42e1a0a6a13998cfcda14ae2bda89657ab22204b0dc49
  • X-TransId is a transaction ID that can be used in debugging with NetFire staff; it can be ignored unless requested by NetFire staff during a support request (this header is present in all Swift responses)
  • X-Openstack-Request-Id is a request ID that can be used in debugging with NetFire staff; it can be ignored unless requested by NetFire staff during a support request (this header is present in all Swift responses)
# BEGIN REQUEST #
GET /auth HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-User: NetFire$example:demo
X-Auth-Key: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 204 No Content
X-Storage-Url: https://us-east1.swift.netfire.com/v1/AUTH_NetFire$example
X-Storage-Token: AUTH_[REDACTED]
X-Auth-Token: AUTH_[REDACTED]
X-Trans-Id: tx00000ab618f0d7669ff62-006517c014-988dd5-us-east1
X-Openstack-Request-Id: tx00000ab618f0d7669ff62-006517c014-988dd5-us-east1
Content-Type: application/json; charset=utf-8
Date: Sat, 30 Sep 2023 06:28:36 GMT
Connection: close
# END RESPONSE #

📘

Note the Storage URL AUTH_ path parameter!

The storage URL, perhaps non-intuitively, is /v1/AUTH_NetFire$example which, per earlier, is in the format of /v1/AUTH_<TenantID>$<UserName> -- NOT /v1/AUTH_<TenantID>$<UserName>:<KeyID>, which is the format you provide for X-Auth-User in the request! The key ID is only used for the authentication request.

You should then provide X-Auth-Token (or X-Storage-Token) and its value in all of your subsequent requests' headers for authenticated requests.

🚧

Currently, Swift tokens expire after 24 hours!

While there is nothing preventing you from generating a new token for each request (and, in fact, many clients/libraries do this automatically), they can be reused multiple time before they expire.

We strongly encourage reusing Swift tokens! Not only is it less load on the NetFire Cloud Storage platform (although the performance hit is quite infinitesimal for generating and returning new tokens), but doing so allows your code to be much more performant as well -- by checking for a 401 status code in responses and only requesting a new token under that condition (or if a token hasn't been requested yet), your code will be able to cut the number of requests your application needs to make roughly in half. That adds up quickly in object storage integrations and can shave seconds or even minutes off of total accumulated runtime latency/delay!

We may reduce the lifetime of tokens for performance and security reasons in the far future if necessary -- this notice will be updated if this change is done -- but currently this is unplanned and likely to not be necessary.