StediDOCS

Authentication

Getting Started

Requests to Stedi APIs are authenticated using a secret token called an API key. Each API key belongs to a single account. In this guide, you will learn how to create an API key and use it to make authenticated calls to the Stedi APIs.

Creating an API key

To create a new API key, click on Identity & Access in the navigation menu, followed by the API Keys tab. Then, click on the Generate API key button located in the top right corner of the page.

Choose a name for your API key that represents the application that will be using this key to access your Stedi account (for example, "ERP Integration"), and click Generate key.

Terminal will display your new API key. This is the only time the full contents of your key can be retrieved, so be sure to copy the key now and save it in a secure location.

Remember: Your API key should be kept secret. Never share it or commit it to source control.

Making authenticated API calls

When making an HTTP request to a Stedi API, pass your API key in the Authorization header, prefixed by the word Key and a space. For example, the following cURL command issues an authenticated request to list the functions in an account:

curl -X GET https://functions.stedi.com/2021-06-01/functions \
  -H "Authorization: Key <your-api-key>" \
  -H "Content-Type: application/json"

A slightly more complex example – using the Axios HTTP client for JavaScript to parse an EDI file. Note: this code snippet expects the API key to be set in the API_KEY environment variable, to avoid committing the secret value to source control.

import axios from "axios";

const ediDocument = `ISA*00*          *00*          *ZZ*SENDERISA      *14*0073268795005  *020226*1534*U*00401*000000001*0*T*>~
GS*PO*SENDERGS*007326879*20020226*1534*1*X*004010~
ST*850*000000001~
BEG*00*SA*A99999-01**19970214~
REF*VR*54321~
ITD*01*3*1**15**16~
DTM*002*19971219~
N1*BT*BUYSNACKS INC.*9*1223334444~
N3*P.O. BOX 0000~
N4*TEMPLE*TX*76503~
PO1**16*CA*12.34**CB*000111111*UA*002840022222~
PID*F****CRUNCHY CHIPS LSS~
PO4*48*7.89*LB~
CTT*7~
SE*35*000000001~
GE*1*1~
IEA*1*000000001~
`;

axios
  .request({
    url: "https://edi-core.stedi.com/2021-06-05/translate",
    method: "POST",
    data: { input: ediDocument, input_format: "edi", output_format: "jedi@1.0" },
    headers: { Authorization: `Key ${process.env.API_KEY}` },
  })
  .then((response) => {
    console.log(JSON.stringify(response.data, undefined, 2));
  })
  .catch((error) => {
    console.error(error);
  });

Recommended security practices

Possession of an API key provides the ability to access and modify data in your Stedi account, so it's important to be sure that untrusted parties are not able to access them.

  • Don't share API keys. Use a different API key for each application that you build on Stedi.
  • Don't commit API keys to source control. Instead, use environment variables or your framework's supported configuration pattern to inject the secret value at runtime.
  • Delete any API keys that are no longer used, or that have been accidentally exposed to an untrusted party.

Service Limits

Each account may have up to 50 API keys at one time.