fulfillmenttools
API documentationIncident ManagementFeedback
Developer Docs
Developer Docs
  • Developer docs
  • Getting Started
    • Quickstart
    • Integration tutorial
      • Adding facilities
      • Adding listings to facilities
      • Configuring stocks
      • Carrier configuration
      • Placing orders
      • Checkout options
      • Distributed Order Management System (Routing)
      • Local fulfillment configuration
    • Free trial
  • Technical Basics
    • Access to fulfillmenttools
    • Feature status
    • Available regions
    • Backup policies
  • Connecting to fulfillmenttools
    • Client SDKs
    • commercetools connect
    • OpenID connect
      • Configure Microsoft Entra ID / Azure Active Directory
      • Configure Keycloak
  • API
    • Core concepts
      • Authentication & authorization
      • API Versioning & lifecycle
      • Assign user to jobs
      • Localization
      • Resource timestamps
      • Custom attributes
      • Article attributes
      • Recordable attributes
      • Data update guarantees
      • Rate limits & scaling
      • Retries
      • Performance on test vs. production systems
      • Load testing
    • API calls
      • Postman
      • cURL
      • GraphQL Explorer
    • GraphQL API
    • RESTful API
      • Pagination interface
      • RapiDoc
      • OpenAPI 3.0 Spec
    • Eventing
      • Structure of an event
      • Available events
        • Event flows
      • Eventing example
      • Event export
  • Integration Guides
    • Basics
      • Article categories
      • Audits
      • Facilities
      • Facility groups
      • GDPR configuration
      • Listings
      • Remote configuration
      • Receipts
      • Search
      • Subscribe to events
      • Sticker
      • Stocks
      • Storage locations
      • Tags
      • Users
    • Channel inventory
    • Inbound process
    • Outbound stocks
    • Purchase order
    • Receipt
    • Routing strategy (context-based multi-config DOMS)
    • Show sticker to clients
    • Stow jobs
  • More Integration Guides
    • Carrier management
      • Introduction to carrier configuration
      • Required data when operating carriers
      • Adding & connecting carriers to facilities
      • Custom carrier
    • Configurations for order fulfillment
      • Picking configuration
      • Packing configuration
      • Handover configuration
      • Printing and document configuration
      • Packing container types
      • Parcel tag configuration
      • Headless order fulfillment
      • Short-pick reasons
      • External documents in order fulfillment
      • Service jobs
      • Load units
      • Running sequence
    • DOMS - distributed order management system (routing)
    • External actions
    • Interfacility transfer
    • Notifications
    • Orders
      • Place your first order
      • Ship-from-store orders
      • Click-and-collect orders
      • Locked orders
      • Order with custom services
      • Bundled items in an order
      • Order process status
    • Availability & promising
    • Returns
Powered by GitBook
On this page
  • Authentication
  • Providing the JWT
  • Authentication request
  • Authentication response
  • Token Refresh
  • Authorization
Edit on GitHub
  1. API
  2. Core concepts

Authentication & authorization

Last updated 23 days ago

Authentication

More authentication information can be found on the .

The fulfillmenttools platform is secured using an external Identity Provider (Google Identity Toolkit) that issues JWT tokens in exchange for a valid username and password. This JWT token securely encodes (among other things) your username, your role, and which facility you are assigned to. Authorization against our API works by using an issued JWT Token in every request as an HTTP header.

Providing the JWT

All requests to the fulfillmenttools platform requiring authentication should contain the following auth header:

Authorization: Bearer {YOUR_ID_TOKEN}

Authentication request

To retrieve an authentication token for a given user, send an HTTP POST call to this API endpoint:

POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={authKey}
{
    "email": "willywonka@ocff-tenantWillyWonka-git.com",
    "password": "myPassword",
    "returnSecureToken": true
}

authKey, email and password have to be valid to your fulfillmenttools instance and are being given to you when the instance was created. The email must follow the format: "<username>@ocff-<tenantName>-<environment>.com".

Overall logins, the identity platform enforces a rate limit of 2000 logins in 60 seconds. This limit can be raised if needed.

Authentication response

As a result, an answer looks similar to this response:

{
  "kind": "identitytoolkit#VerifyPasswordResponse",
  "localId": "jdwBuqqYWdYoqWTH1Xv85EJJMpm2",
  "email": "willy@wonkacandycompany.com",
  "displayName": "Willy Wonka",
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZ...ynLgbiNgHJJxtBXSTSFnp2fA",
  "registered": true,
  "refreshToken": "AE0u-NeGDdHWPB0RjOYO...pRMKoncagBq30OFCJkEgpvyI",
  "expiresIn": "3600"
}

Two attributes in the above response are of special importance:

  1. idToken is the actual JWT you need to send along every REST Call you issue against the fulfillmenttools API. It has an expiration period depicted by the attribute expiresIn. In this case, it is valid for 3600 seconds. After that, you need to get a fresh token.

  2. refreshToken should be used to get a fresh token without providing the credentials again.

Every call to the fulfillmenttools API must include the JWT in an Authorization-Bearer header.

Token Refresh

To refresh a token, send an HTTP POST call to this API endpoint:

POST https://securetoken.googleapis.com/v1/token?grant_type=refresh_token&refresh_token={refreshToken}&key={authKey}

Authorization

fulfillmenttools have a simple roles and permissions system that cannot be edited currently. Depending on the role, the corresponding user has access to data (or not) for which he has the necessary authorization. The prerequisite is, of course, a valid authentication.

A user must always have exactly one assigned role, reflected in the JWT. That means a role switch is available after a token refresh.

There is a fixed set of roles a user can take within the platform:

Role
Facility affiliation
Description

FULFILLER

yes

Takes care of the operative workflow, such as picking or packing. Users have primarily access to operatively needed parts of the system.

SUPERVISOR

yes

Supervisor role extends the role of the Fulfiller. It is allowed to configure the settings of certain facilities.

ADMINISTRATOR

no

The Administrator of a fulfillmenttools system is allowed to access all the functionality.

Furthermore, there is an imposed rate limit on calls towards the Google Identity Toolkit for new tokens based on username & password (see ). This could be especially relevant for connector implementations as it might be feasible to cache & share tokens between function invocations.

Google Identity Platform - Quotas
Google Identity Toolkit API website
Drawing