Skip to main content
↓ Download as Markdown

Obtaining an API Client

To build an integration that uses the Future Ordering APIs, you need an API Client. An API Client consists of credentials (a client ID and secret) that authenticate your integration and determine which APIs it can access.

Important: The Customer Must Request the Client​

The API Client must be requested by someone at your customer organization, not by the integrator or partner building the integration. This is because the API Client provides access to the customer's sensitive business data. Only authorized personnel at the customer organization may request creation, or extending permissions, of an API Client.

If you are an integrator or partner building on behalf of a customer, ask a representative from the customer's organization (such as their IT administrator or technical lead) to submit the request on your behalf.

Information Required for Your Support Request​

When requesting an API Client, your support request must include the following information:

1. Contact Details for Secure Delivery​

Since API Client credentials are sensitive, they are delivered through a secure process that uses two separate communication channels:

  • One channel for sending the encrypted credentials file
  • A different channel for sending the password/key to decrypt the file

Please provide:

  • Primary contact email: Where the encrypted credentials should be sent
  • Secondary contact email or phone: Where the decryption password should be sent (must be different from the primary contact method)
note

Do not share the decryption password and credentials file through the same channel. This two-part delivery process ensures that intercepting one communication channel does not compromise your credentials.

2. Use Case Description​

Describe what the API Client will be used for. This information is used to name the API Client for easier management. Be specific:

  • Examples: "Inventory Sync Service", "Sales Statistics Integration", "Device Automation Integration", "External Payment Provider", "Loyalty Integration - An integration which will expose APIs for frontend plugins, calculate discounts for orders and interpret scanned codes"
  • This helps Future Ordering support staff quickly identify the purpose of the client to be able to assist with any future questions.

3. Required Endpoints or Permissions​

List the specific APIs and endpoints your integration needs to access. This determines the permissions granted to the API Client and ensures that it only has the access it requires, following the principle of least privilege.

Examples of endpoints to request access to:

GET /users
GET /users/\{user-id}
GET /orders/\{order-id}
GET /orders/\{order-id}/deals
POST /orders/\{order-id}/deals
PATCH /orders/\{order-id}/deals

If you're unsure which permissions you need, our support team can help determine this based on your use case description.

note

If you do not know exactly which endpoints your API Client should have access to, you can write a list similar to:

  • Read any user account's personal data
  • Read data for any order, including personal data
  • Read deals
  • Create deals
  • Submit discount calculations

However, there is a risk this will give your API Client more or fewer permissions than needed.

4. Whether or Not the API Client Should Have Access to Personal Data​

Receiving access to personal data requires a specific permission for that specific purpose. This is done in order to allow API Clients which, for example, retrieve order data without being able to also retrieve Personal Data on the order.

Remember to always protect end-users personal data and do not expose or process it unless absolutely needed, and remember that processing personal data in new locations / partners might require updating the Terms of Services.

When requesting the API Client, make it exlicitly clear whether the API Client should be able to access personal data or not.

4. Tenant IDs​

Specify which tenant(s) the API Client should have access to. A tenant corresponds to a customer environment in Future Ordering. If your organization has more than one tenant, list all tenant IDs that the integration requires access to.

If you are unsure of your tenant ID(s), contact your Future Ordering account representative.

5. Environments​

Specify which environments the API Client should be created for:

  • Test: Used for development and testing
  • Production: Used for live operations

Clients are created and managed per environment.

note

It is strongly recommended to request a test environment client to validate your integration before requesting a production client.

How to Request an API Client​

  1. Contact Future Ordering support at support@futureordering.com - Include "API Client Request" in the subject line to help route your request quickly
  2. Provide all pieces of information listed above

Our support team will validate the request, create the API Client and send the API Client details to the provided contacts.

Asking for Extended Permissions for an Existing API Client​

In your request, please include the Client ID and the list of new permissions the API Client should receive.

If your API Client is no longer using one or more APIs that your API Client has permissions to, it is recommended to send a request to remove permissions that are not needed.

Security Considerations​

Once you have your API Client credentials:

note
  • Treat credentials as secrets: Your client secret is sensitive authentication material. Protect it as you would a password.
  • Do not commit to version control: Never store your client ID or secret in source code repositories, configuration files, or any version control system.
  • Use environment variables: Store credentials in environment variables or secure configuration management systems.
  • Limit distribution: Only share credentials with team members who absolutely need them to maintain or operate the integration.
  • Limit permissions: Request only the permissions you need for your integration.

For more details on how to use your credentials once they're obtained, see the Authentication guide.

Sample Support Request​

Here's an example of what a complete support request should look like:

Subject: API Client Request - Loyalty Integration

Hi,

I am requesting an API Client for our new loyalty integration.

PRIMARY CONTACT (for encrypted credentials): 
E-mail Address: jane.developer@company.com

SECONDARY CONTACT (for decryption password): 
Phone number: +00 123 456 789

USE CASE:
The API Client will be used for "Loyalty Integration" - a system that reads
user and order data from Future Ordering to calculate loyalty rewards, and
submits deals and discount calculations back to Future Ordering.

REQUIRED ENDPOINTS AND PERMISSIONS:

GET /users
GET /users/\{user-id}
GET /orders/\{order-id}
GET /orders/\{order-id}/deals
POST /orders/\{order-id}/deals
PATCH /orders/\{order-id}/deals

SHOULD BE ABLE TO READ PERSONAL DATA (Y/N):
Yes

TENANTS:
Test Environment: my-tenant-id
Production Environment: my-tenant-id
Production Environment: my-other-tenant-id

Thank you

What to Expect​

  • Response time: Support will typically acknowledge your request within 1 business day
  • Processing time: Complete processing usually takes 1-5 business days, depending on workload and clarity of request
  • Delivery: Credentials will be delivered in two separate messages through the specified channels
  • Testing: After receiving credentials, you can immediately begin testing in the test environment

For more information, once you have received your credentials, refer to the Getting Started guide.