# API credentials
API credentials are essential to [obtain an access token](#core-api-credentials) from [Commerce Core Layer API](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/RWJeylueWkzLadK710XZ/) authorization endpoints so that you can make authenticated API calls or [create the available Dashboard apps](#dashboard-apps-api-credentials) in case you're building your own Dashboard or extending the current one.
Each API credential is [organization](https://docs.commercelayer.io/provisioning/api-reference/organizations)-specific and to [create a new one](https://docs.commercelayer.io/provisioning/api-reference/api_credentials/create) you just need to provide a name and specify the API credential `kind`.
{% hint style="warning" %}
Please note that only *Admins* (i.e. users with an `admin` role) can perform all the CRUD actions on the API credentials of an organization, while *Members* (i.e. users with a `read_only` or `custom` role) are allowed only to [retrieve](https://docs.commercelayer.io/provisioning/api-reference/api_credentials/retrieve) a specific API credential and/or to [fetch a list](https://docs.commercelayer.io/provisioning/api-reference/api_credentials/list) of API credentials.
{% endhint %}
## Core API credentials
To use [Commerce Core Layer API](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/RWJeylueWkzLadK710XZ/) you need to be [authorized](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/authentication) in the first place. This means you need to get a valid access token. The permissions you're granted on each single resource authenticating with that token are determined by the type of API client you used to get it. Three different types of Core API credentials are currently available: `sales_channel`, `integration`, and `webapp`. Which one to use depends on your specific [use case](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials).
{% hint style="info" %}
To create `integration` API credentials you also need to assign them a [role](https://docs.commercelayer.io/provisioning/api-reference/roles) with specific [permissions](https://docs.commercelayer.io/provisioning/api-reference/permissions). You cannot assign a role to `sales_channel` and `webapp` API credentials.
{% endhint %}
### Sales channel
API credentials of kind `sales_channel` are used to build any customer touchpoint (e.g. your storefront with a fully functional shopping cart and checkout flow). They are *not confidential* (public) and their roles and permissions are restricted so that they can be safely used client-side and their tokens exposed to the public without any risks.
### Integration
API credentials of kind `integration` are used to develop backend integrations with any 3rd-party system. They are *confidential* and can have one of two roles: `admin` or `read_only`.
{% hint style="info" %}
[Enterprise](https://commercelayer.io/pricing) users can also define [custom roles](https://docs.commercelayer.io/provisioning/roles#custom-roles) for their integration applications, specifying custom permissions on CRUD actions at the single resource level.
{% endhint %}
### Webapp
API credentials of kind `webapp` are used to develop custom web apps or services for your users, extending Commerce Layer backend with any functionality that is not provided out of the box. You can use them to execute the OAuth 2.0 [authorization code](https://docs.commercelayer.io/provisioning/api-reference/permissions) grant flow to get an access token after a user authorizes an app. They don't come with their own roles and permissions, since they get the set of permissions of the authenticated user.
## Access token expiry
For security reasons, access tokens expire after a default period of time. Your access token lifetime differs [based on the kind of application you're using](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/authentication#access-token-expiry). You can specify a custom lifetime for the token by setting the `expires_in` attribute at creation time or when updating a specific API credential.
{% hint style="info" %}
The token lifetime value must be expressed **in seconds** and fall within a **min** of **2 hours** (**7200 secs**) and a **max** of **15 days** (**1296000 secs**).
{% endhint %}
{% hint style="warning" %}
To avoid security issues, be careful not to set too long expiration dates for your access tokens.
{% endhint %}
## Dashboard apps API credentials
Each available Dashboard app has its own API credential `kind` (e.g. `orders`, `shipments`, `imports`, etc.) and comes with its predefined set of permissions in terms of CRUD action on the Core API resources. For more details about that please refer to the [related section](https://docs.commercelayer.io/provisioning/getting-started/applications) of the documentation:
{% content-ref url="../getting-started/applications" %}
[applications](https://docs.commercelayer.io/provisioning/getting-started/applications)
{% endcontent-ref %}
### Creating a hosted Dashboard app
The hosted version of any Dashboard apps can be created from the Dashboard UI by simply clicking on the related item of the dropdowns in the left sidebar (e.g. *Fulfillment > Shipments*). That will create two API credentials of the selected kind, one for the *test* mode and the other for the *live* mode:
To do that via API you need to send a `POST` request to the `/api/api_credentials` endpoint, passing the specific `name` and `kind` as arguments in the request body:
{% tabs %}
{% tab title="Request" %}
The following request creates the hosted *Shipments* app in *live* mode for the organization identified by the ID "ABCRtyUpBa":
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created resource object:
```json
{
"data": {
"id": "rpodBiRAON",
"type": "api_credentials",
"links": { ... },
"attributes": {
"name": "Shipments",
"kind": "shipments",
"confidential": true,
"redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
"client_id": "XxYyZz__cl13nTID",
"client_secret": "CL1eNTs3cRetXyZyKkXx",
"scopes": "market:all",
"expires_in": "7200",
"mode": "live",
"custom": false,
"created_at": "2024-01-01T12:00:00.000Z",
"updated_at": "2024-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": null
},
"relationships": {
"organization": { ... },
"role": { ... }
}
}
}
```
{% endtab %}
{% endtabs %}
### Creating a custom Dashboard app
Any Dashboard apps can be customized at your leisure by creating a new repository from [this template](https://github.com/new?template_owner=commercelayer\&template_name=dashboard-apps) and leveraging [this guide](https://deploy-preview-690--commercelayer-app-elements.netlify.app/?path=/docs/getting-started-custom-apps--docs#how-to-customize-an-application) to seamlessly integrate your custom version in the Dashboard itself. That can be done from the Dashboard UI by selecting the *Custom apps* item from the *Developers* dropdown, clicking on the *+ Custom app* button, and following the simple steps of the wizard:
To create a custom app via API, send a `POST` request to the `/api/api_credentials` endpoint, passing the `kind` of the app you want to fork and the `name` you want to give to your custom app as arguments in the request body.
{% hint style="warning" %}
Make also sure to set the `custom` attribute to `true` and the URL where you're deploying your custom app as the `redirect_uri.`
{% endhint %}
{% tabs %}
{% tab title="Request" %}
The following request creates a custom version of the *Orders* app in *test* mode for the organization identified by the ID "ABCRtyUpBa":
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created resource object:
```json
{
"data": {
"id": "AGPkZiarvN",
"type": "api_credentials",
"links": { ... },
"attributes": {
"name": "My Orders App",
"kind": "orders",
"confidential": true,
"redirect_uri": "https://mybrand.com/orders",
"client_id": "KkWwHh__cl13nTID",
"client_secret": "CL1eNTs3cRetZxZyKv",
"scopes": "market:all",
"expires_in": "7200",
"mode": "test",
"custom": true,
"created_at": "2024-01-01T12:00:00.000Z",
"updated_at": "2024-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": null
},
"relationships": {
"organization": { ... },
"role": { ... }
}
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
The newly created app will be automatically added to the Dashboard under the *Custom apps* section.
{% endhint %}
### Resources API credentials
API credentials of kind `resources` are automatically generated as soon as a new [organization](https://docs.commercelayer.io/provisioning/api-reference/organizations) is created. They are used to populate and manage the *Resources* section of the Dashboard.
{% hint style="info" %}
Resources API credentials are **read-only**, meaning that they cannot be created, deleted, or forked by the user. They are anyway returned when you [fetch the list](https://docs.commercelayer.io/provisioning/api-reference/api_credentials/list) of an organization's API credentials.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.commercelayer.io/provisioning/api-reference/api_credentials.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
