{"id":18810984,"url":"https://github.com/shipengine/elements-auth-example","last_synced_at":"2026-01-11T02:30:14.613Z","repository":{"id":215488966,"uuid":"706780919","full_name":"ShipEngine/elements-auth-example","owner":"ShipEngine","description":"Example application for handling ShipEngine Elements authentication token requests.","archived":false,"fork":false,"pushed_at":"2024-06-25T14:17:22.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-12-29T23:49:05.170Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ShipEngine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-18T15:49:07.000Z","updated_at":"2024-06-25T14:17:25.000Z","dependencies_parsed_at":"2024-04-11T18:34:16.655Z","dependency_job_id":"88b0cfb5-2b26-4ae0-86f0-8b65943b0f1b","html_url":"https://github.com/ShipEngine/elements-auth-example","commit_stats":null,"previous_names":["shipengine/elements-auth-example"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShipEngine%2Felements-auth-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShipEngine%2Felements-auth-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShipEngine%2Felements-auth-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShipEngine%2Felements-auth-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ShipEngine","download_url":"https://codeload.github.com/ShipEngine/elements-auth-example/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239748254,"owners_count":19690232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T23:23:40.707Z","updated_at":"2025-02-19T22:41:37.704Z","avatar_url":"https://github.com/ShipEngine.png","language":"JavaScript","readme":"# elements-auth-example\n\nExample application for handling ShipEngine Elements authentication token requests.\n\n## Pre-requisites\n\n- node.js\n- yarn preferably but npm will work\n- The following shipengine credentials\n  - token issuer\n  - partner api key\n  - scope\n- A private rsa key that matches the public key that has been submited to your ShipEngine Account Manager\n- A tenant id must be generated before hand and provided to the application. [Official Documentation](https://www.shipengine.com/docs/partners/accounts/create/)\n\n## How to Start\n\n1. Install dependencies\n\n```bash\nnpm install\n```\n\nor\n\n```bash\nyarn\n```\n\n2. Start the application\n\n- a. Start application for production\n\n```bash\nnpm start\n```\n\nor\n\n```bash\nyarn start\n```\n\n- b. Start application for development\n\n```bash\nnpm dev\n```\n\nor\n\n```bash\nyarn dev\n```\n\n## How to Configure\n\nThe application uses an express server to serve your token generation requests, and uses the `dotenv` package to read your configuration values from a `.env` file.\n\nYou'll need to provide a .env file at the root of the project directory.\n\nA template `.env` file is provided in the root of the repository as `.env.template`. You can copy this file and rename it to `.env` and fill in the required values.\n\nHere is an example of the final product in case you need it, the only value that may need attention is the `PRIVATE_KEY` as it is a multi-line string.\nExample of environment file (`.env`)\n\n```env\nPRIVATE_KEY_FILENAME=value\nPLATFORM_TOKEN_ISSUER=value\nPLATFORM_TOKEN_KEY_ID=value\nSCOPE=value\nSHIPENGINE_PARTNER_ID=value\nSHIPENGINE_PARTNER_API_KEY=value\nSHIPENGINE_TENANT=value\nPORT=value\nPATH_GENERATE_TOKEN=/value\nPRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----\nmultiple\nline\nvalue\n-----END PRIVATE KEY-----\"\n```\n\n### Required Configuration Options\n\nThe `.env.template` provides comments to guide you along the process, but in case you want a more detailed reference, refer to the chart below\n\n**Note:** Required fields do not provide default values\n\n| Configuration Field            | Description                                                                                                                                                                                                        |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **PLATFORM_TOKEN_ISSUER**      | Used to validate the source of the generated token. This value will be provided to you by your Account Manager after your public RSA key has been submitted.                                                       |\n| **PLATFORM_TOKEN_KEY_ID**      | Used as an identifier for the public RSA key that was submitted to your Account Manager. This value will be provided to you by your Account Manager after your public RSA key has been submitted.                  |\n| **SCOPE**                      | Used to determine the permissions for the generated token. This value will be provided to you by your Account Manager.                                                                                             |\n| **SHIPENGINE_PARTNER_ID**      | Your ShipEngine Account Identification, unique to your organization, not to be confused with a tenantId. This is provided for you by your Account Manager when you register to the ShipEngine Partner program.     |\n| **SHIPENGINE_PARTNER_API_KEY** | Your ShipEngine API key unique to your organization, not to be confused with an individual seller's API key. This is provided for you by your Account Manager when you register to the ShipEngine Partner program. |\n\n### Optional Configuration Options\n\n| Configuration Field      | Description                                                                                              | Default Value       |\n| ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------- |\n| **PORT**                 | The port number on which the application runs.                                                           | _3002_              |\n| **TOKEN_ENDPOINT**       | The endpoint for token generation requests.                                                              | _'/generate-token'_ |\n| **SELLER_ENDPOINT**      | The endpoint for new tenant (seller) creation requests.                                                  | _'/create-seller'_  |\n| **SHIPENGINE_TENANT_ID** | Tenant id can optionally be provided if tokens need to be generated only for one specific seller account | _Empty_             |\n\n**Tip:** Documentation for all the fields outlined is described in the [Elements Guide Documentation](https://www.shipengine.com/docs/elements/elements-guide/#elements-jwt-generation)\n\n## How to Use\n\nOnce the server is running, it can be used to both generate authentication tokens needed for Elements, as well as creating new ShipEngine seller accounts.\n\n### Generate a Token\n\nTo generate an authentication token to be used with Elements, send a `GET` request to the configured `TOKEN_ENDPOINT`, adding the ShipEngine Seller account ID as the `tenantId` to the path. For the default configuration this would be:\n\n```text\nGET http://localhost:3002/generate-token/{tenantId}\n```\n\nIf you have configured a default seller account with `SHIPENGINE_TENANT_ID`, the `tenantId` path variable can be omitted:\n\n```text\nGET http://localhost:3002/generate-token\n```\n\n### Create a New Seller Account\n\nTo create a new seller account, send a `POST` request to the configured `SELLER_ENDPOINT`. For the default configuration, this would be:\n\n```text\nPOST http://localhost:3002/create-seller\n```\n\nThe body of the request should contain a JSON object with the account properties:\n\n```js\n{\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"email\": \"jdoe@example.com\",\n    \"company\": \"ShipCo\",\n    \"accountId\": \"12345\",\n    \"country\": \"US\"\n}\n```\n\nBelow are the properties that may be sent in the request body. All properties are optional:\n\n| Body Field    | Description                                                                                                                                                                                                                                           |\n| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **firstName** | The given name of the seller. If not provided, a random value will be generated.                                                                                                                                                                      |\n| **lastName**  | The family name of the seller. If not provided, a random value will be generated.                                                                                                                                                                     |\n| **email**     | The email address for the seller. This value must be unique, and account creation will fail if a duplicate value is used. If an address is not provided, a unique value will be generated based on the contact address within your partner account.   |\n| **company**   | The seller's company name. If not provided, this will be set based on your partner account.                                                                                                                                                           |\n| **accountId** | An optional external account ID. This can be set to the user's account ID within your own system, which will allow you to look up the seller account using that external ID using the ShipEngine API. If not provided, this field will be left empty. |\n| **country**   | The two-character country code for the seller's home country. If not provided, this will default to `\"US\"`.                                                                                                                                           |\n\nThis request will respond with the ShipEngine seller object as described in the [Shipengine API Documentation](https://www.shipengine.com/docs/partners/accounts/create/). The most important value returned for the general Elements use case is the `account_id` property, which must be used as the `tenantId` when generating a token for this seller.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshipengine%2Felements-auth-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshipengine%2Felements-auth-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshipengine%2Felements-auth-example/lists"}