Learn how to to get started managing content.

Getting Started


## Welcome to Brightlever CMS

Brightlever is a pure SaaS system that is currently under development. It is designed to be extremely straightforward and easy to use. 

The main components of Brightlever are:

- Organizations
- Projects
- Environments
- Content Types
- Documents







Brightlever: A Modern Lightweight Headless CMS for your Enterprise Data.

Welcome to Brightlever CMS

Organizations are the top level objects for managing projects.  By default a user's membership doesn't neccesarily grant
to manage any content. Rather, membership denotes a user a being a candidate for project environment access. 

Organization admins automatically have admin access to all of the organization's projects and associated environments.

Organizations

Projects are very simple. They are used to aggregate environments for a related purpose, like a client or use case.

You may create a project for a custom application.  You can then create a DEV, UAT and PROD envrionments to parallel common
patterns is software management.

Or you could consider a client as a project "ABC Corp" and then create an environment for each content deployment that the
client requires.

Organization members only see projects that are associated with environments to which the member has been
granted access.

Projects

Envrionments are content deployments to which organization members can be granted access. 

By default organization admins are also envronment admins.  To grant access to none admins
you must first create an Access Role with the desired permissions. Then you can assign that 
role to the organization member.

Organization members only see environments which they have been granted access.


Environments

Content Types define what a particular document should contains and stores them together in 
a document collection that be destributed to client applications.

```
{
  "name": "Person",
  "properties": [
    {
      "listView": true,
      "labelView": true,
      "useEnum": false,
      "title": "First Name",
      "required": true,
      "key": "firstName",
      "pattern": "",
      "type": "text"
    },
    {
      "key": "lastName",
      "localized": false,
      "labelView": true,
      "type": "text",
      "useEnum": false,
      "title": "Last Name",
      "listView": true,
      "required": true,
      "pattern": ""
    },
    {
      "key": "profileImg",
      "localized": false,
      "pattern": "",
      "listView": false,
      "labelView": false,
      "useEnum": false,
      "title": "Profile Picture",
      "type": "file",
      "required": false
    },
    {
      "title": "Job TItle",
      "localized": true,
      "key": "jobTitle",
      "labelView": false,
      "pattern": "",
      "useEnum": false,
      "listView": true,
      "required": false,
      "type": "text"
    },
    {
      "listView": false,
      "required": false,
      "type": "html",
      "useEnum": false,
      "localized": false,
      "labelView": false,
      "pattern": "",
      "key": "bio",
      "title": "Bio"
    },
    {
      "itemTitle": "hobby",
      "useEnum": false,
      "key": "hobbies",
      "labelView": false,
      "listView": false,
      "type": "array",
      "localized": false,
      "items": {
        "useEnum": false,
        "type": "text",
        "pattern": ""
      },
      "required": false,
      "title": "Hobbies"
    },
    {
      "required": false,
      "localized": false,
      "key": "favoriteNum",
      "listView": false,
      "labelView": false,
      "type": "number",
      "title": "Favorite No",
      "useEnum": false
    }
  ],
  "id": "person"
}
```




Content Types

Documents are instances of JSON documents created per content type definitions.
They are the final product.

```
{
  "id": "NLHxtKAqHdwKpoN58gYM",
  "bio": "<p>I'm a dog</p>",
  "hobbies": [],
  "jobTitle": {
    "en": "dog",
    "es": "perro",
    "ru": "собака"
  },
  "lastName": "Levine",
  "firstName": "Thatcher",
  "favoriteNum": 22
}
```






Documents

Get started with the platform and learn how to use it.

Content Type Schemas


## Basic Structure

Content Type schemas are stored as a JSON document consisting of the schema's id, name and properties.


**id:** Is the envrionmentally unique string identifier that will be used to access the documents associated with this schema's property definition. 
It cannot be chance once the schema is saved.

**name:** Is the name used within the Brightlever UI to represent documents of content type.

**description:** A description of what the schema properties are describing.

**properties:** Is an array of properties that define the actual schema properties.

**Example:**

```
{
  "name": "widget",
  "id": "widget",
  "properties": [
    {
      "listView": true,
      "localized": true,
      "type": "text",
      "title": "Name",
      "useEnum": false,
      "key": "name",
      "labelView": true,
      "required": true
    },
    {
      "listView": false,
      "localized": false,
      "type": "html",
      "title": "Description",
      "useEnum": false,
      "labelView": false,
      "required": false,
      "key": "description"
    },
    {
      "listView": false,
      "localized": false,
      "type": "file",
      "title": "Image",
      "useEnum": false,
      "labelView": false,
      "required": false,
      "key": "image"
    }
  ]
}
```

## Property Attributes

**listView:** This denotes if the property should be include in the default list view UI.

**localized:** This denotes if the property should be localized.  
If true, the property will be saved as an object with a key per localized property value.

```
{
    "jobTitle": {
        "en": "bureaucrat",
        "es": "burócrata",
        "ru": "бюрократ"
    }
}
```

**title:** Denote the how the Brighllever UI should refer to the property.

**key:** Denotes the value that the property should be refered to via programmatic apis.

**description:** A description of the purpose of the property.

**type:** Denotes the data type that is expected as the property value.

**useEnum:** Denotes if the property should have a predefined set of values (string and number only).
 
**labelView:** Denotes if the property should be used when create labels for content type instances.

**required:** Denotes if the propery requires a value if the documents is to be considered valid.

**enum:** For use with properties that have useEnum set to true. 

example: 

``` 
    ...,
    {
        "type": "text",
        "useEnum": true,
        "enum": [
            "Rickenbacker",
            "Gretsch"
        ],
        "listView": false,
        "labelView": false,
        "required": false,
        "localized": false,
        "title": "Guitar Type",
        "key": "guitarType"
    },
    ...
```

**items:** For use with properties with the type set to "array". It defines what is expected to populated the array. 

example:

```
    ...,
    {
      "type": "array",
      "items": {
        "type": "text",
        "useEnum": false
      },
      "useEnum": false,
      "listView": false,
      "labelView": false,
      "required": false,
      "localized": false,
      "title": "Options",
      "itemTitle": "option",
      "key": "options"
    },
    ...
```

**itemTitle:** Used with properties with the type of array to denote how to refer to items within the resulting array.

**properties:** Use with properties with teh type of object to denote what properties should be expected.

example:

```     
    ...,
    {
        "title": "My Object",
        "key": "myObject"
        "type": "object"
        "properties": [
            {
                "listView": true,
                "localized": true,
                "type": "text",
                "title": "Name",
                "useEnum": false,
                "key": "name",
                "labelView": true,
                "required": true
            },
            {
                "listView": false,
                "localized": false,
                "type": "html",
                "title": "Description",
                "useEnum": false,
                "labelView": false,
                "required": false,
                "key": "description"
            }
        ]
    },
    ...

```

## Property Types

**text**

**longtext**

**html**

**markdown**

**number**

**boolean**

**object**

**array**

**tel**

**date**

**datetime**

**email**

**time**

**password**

**color**

**file**

**url**

**has-one**

**has-many**

**tags**


APIs


There are four endpoints used to access api methods.

### api.brightlever.app

This the CMA (content management api) endpoint.  It should be used for all content management usecases.

### cdn.brightlever.app

This the CDA (content distribution api) endpoint.  It provides read only access to the currently published documents.

### preview.brightlever.app

This the preview endpoint.  It provides read only access to the latest version of each documents.

### storage.brightlever.app

This the file storage endpoint.  This is where the file upload assets are delivered to the client from.




Endpoints

## List

**GET: /v1/environments/\{environment_id}/content_types**

Retrieves collection of content types from a specific environent.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## Read

**get: /v1/environments/\{environment_id}/content_types/\{content_type}**

Reads a content type.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|


## Upsert

**post: /v1/environments/\{environment_id}/content_types/\{content_type}**

Update for creates a content type.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

**Body**

Set the JSON descriptor object as the `formData` key in the the JSON body.

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `body`  | JSON | Document to save|

## Delete

**delete: /v1/environments/\{environment_id}/content_types/\{content_type}**

Deletes a content type.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|


Content Type API

## Find Query

**GET: /v1/environments/\{environment_id}/entries/\{content_type}**

Retrieves collection of documents from a specific content type.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|

**Query string Parameters**

For semantic searching use `where[_semantic_search][eq]={searchstring}`.

| Parameter     | Type    | Description                                                     | Default |
| ------------- | ------- | --------------------------------------------------------------- | ------------- |
| `where[{property}][eq]` | string,number | value for comparison         | null     |
| `where[{property}][neq]` | string,number | value for comparison         | null     |
| `where[{property}][gt]` | string,number | value for comparison         | null     |
| `where[{property}][gte]` | string,number | value for comparison         | null     |
| `where[{property}][lt]` | string,number | value for comparison         | null     |
| `where[{property}][lt]` | string,number | value for comparison         | null     |
| `where[{property}][in]` | string,number | value for comparison         | null     |
| `where[{property}][notIn]` | string,number | value for comparison         | null     |
| `where[{property}][begins]` | string,number | value for comparison         | null     |
| `where[{property}][ends]` | string,number | value for comparison         | null     |
| `aggregate[count]` | - | count(*) | - |
| `aggregate[{property}][sum]` | - | num(property) | - |
| `aggregate[{property}][avg]` | - | avg(property) | - |
| `aggregate[{property}][min]` | - | min(property) | - |
| `aggregate[{property}][max]` | - | max(property) | - |
| `aggregate[{property}][or]` | - | or | - |
| `aggregate[{property}][or][openGrouping]` | - | or ( | - |
| `aggregate[{property}][openGrouping]` | - | and ( | - |
| `aggregate[{property}][closeGrouping]` | - | )  | - |
| `select[{propertyList}]` | - | Comma seperate list |  null |
| `populate[{propertyList}]` | - | Comma seperate list, used to populate relationships |  null |
| `orderBy[{property}]` |  string | "desc" or "asc" | "asc" |
| `pagination[page]` | number | page index to return | 0 |
| `pagination[pageSize]` | number | page size to return | 10 |

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## Upsert

**post: /v1/environments/\{environment_id}/entries/\{content_type}/\{doc_id}**

Creates or updates a document in a collection.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|
| `doc_id`  | string | To id of the document to create or update |

**Body**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `body`  | JSON | Document to save|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `content-type`  | string | "application/json; charset=utf-8"|
| `authorization`  | string | Bearer token set to access_token or API key.|
| `x-brightlever-action`  | string | Optional, set to "publish" if desired.|
| `x-brightlever-source-id` | string | The sourceId associated with a webhook action. |

## Validate

**post: /v1/environments/\{environment_id}/entries/\{content_type}/\{doc_id}**

Return document validation.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|

**Body**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `body`  | JSON | Document to save|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `content-type`  | string | "application/json; charset=utf-8"|
| `x-brightlever-action`  | string | Set to "validate".|
| `authorization`  | string | Bearer token set to access_token or API key.|

## Read

**get: /v1/environments/\{environment_id}/entries/\{content_type}/\{doc_id}**

Reads a document from a collection.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|
| `doc_id`  | string | To id of the document to read |

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## Delete

**delete: /v1/environments/\{environment_id}/entries/\{content_type}/\{doc_id}**

Deletes a document from a collection.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|
| `doc_id`  | string | To id of the document to delete |

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|
| `x-brightlever-source-id` | string | The sourceId associated with a webhook action. |

## Rollback

**post: /v1/environments/\{environment_id}/entries/\{content_type}/\{doc_id}/rollback**

Rolls document back to the previous published version.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|
| `doc_id`  | string | To id of the document to rollback |
| `x-brightlever-source-id` | string | The sourceId associated with a webhook action. |

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## Publish

**post: /v1/environments/\{environment_id}/entries/\{content_type}/\{doc_id}/publish/\{version_id}**

Publishes a prexisting document document version.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|
| `doc_id`  | string | To id of the document |
| `version_id`  | string | To version_id of the document to publish |
| `x-brightlever-source-id` | string | The sourceId associated with a webhook action. |

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## History

**get: /v1/environments/\{environment_id}/entries/\{content_type}/\{doc_id}/history**

This endpoint is not yet implemented. It will return the version history of the document.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|
| `doc_id`  | string | To id of the document to delete |

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## Generate

**post: /v1/environments/\{environment_id}/entries/\{content_type}**

This generates one or more documents based on the the prompt.

If you pass a document with the request then the prompt will be used to update the document.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | string | The associated environment id|
| `content_type`  | string | The associated content type|

**Body**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `body`  | JSON | \{document?:object, prompt:string} |

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `content-type`  | string | "application/json; charset=utf-8"|
| `x-brightlever-action`  | string | Set to "generate".|
| `authorization`  | string | Bearer token set to access_token or API key.|


Document API


## List

**get: /v1/environments/\{environment_id}/content_types/\{content_type}/storage/assets**

Retrieves assets associated with content type.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## Metadata

**get: /v1/environments/\{environment_id}/content_types/\{content_type}/storage/assets/\{file_id}**

Reads a file metadata.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|
| `file_id`  | String | The associated file id|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|

## Duplicate

**post: /v1/environments/\{environment_id}/content_types/\{content_type}/storage/duplicate/\{file_id}**

Duplicates associated file id and returns metadata.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|
| `file_id`  | String | The associated file id|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|
| `x-brightlever-source-id` | string | The sourceId associated with a webhook action. |

## Delete

**delete: /v1/environments/\{environment_id}/content_types/\{content_type}/storage/assets/\{file_id}**

delete associated file id.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|
| `file_id`  | String | The associated file id|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `authorization`  | string | Bearer token set to access_token or API key.|
| `x-brightlever-source-id` | string | The sourceId associated with a webhook action. |

## Upload

**post: /v1/environments/\{environment_id}/content_types/\{content_type}/storage/assets/\{file_id}**

Uploads new file to content types assets.

**Path Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `environment_id`  | String | The associated environment id|
| `content_type`  | String | The associated content type|

**POST Parameters**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `file`  | File | File to upload|
| `overwrite`  | String | "true" or "false" |
| `filename`  | String | Optional, desired filename|

**Headers**

| Parameter  | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `content-type`  | string | "application/x-www-form-urlencoded"
| `authorization`  | string | Bearer token set to access_token or API key.|
| `x-brightlever-source-id` | string | The sourceId associated with a webhook action. |


Storage API

Learn about the options for securely connecting to the Brightlever API.

Authentication


Access roles are used to create specific boundaries to what a user can do with their authticated connection to the Brightlever api. They are managed at the environment admin level.

Per content type an access role can be assigned the following permissions:

**Read.latest**

**Read.published**

**Doc.create**

**Doc.update**	

**Doc.delete**	

**Doc.publish**	

**Schema.define**

Access Roles

API Keys are tokens that can be created and use as access_token for accessing the Brighlever api.  They are managed at the environment admin level.

Api Keys are assigned an access role to assign specific boundaries to what a user can do with it.

They can be passed along with API requests as an Authorization Bearer Token or an `access_token` query string variable.

API Keys

OAuth 2.0 Implicit Grant Workflow for Brightlever Integration
This guide outlines the steps to integrate your application with Brightlever's APIs using the OAuth 2.0 Implicit Grant type. Note: The Implicit Grant is less secure than the Authorization Code Grant and is generally recommended only for specific scenarios (e.g., browser-based applications where a backend server is not involved).

## 1. Register Your Application
Log in to the Brightlever and go to your environment admin.
Create a new application and provide the following information:
Application Name: A descriptive name for your application.
Redirect URI: The URI your application will redirect to after the user grants authorization (e.g., https://your-app.com/callback).
Upon successful registration, you'll receive a Client ID. Keep this confidential.

## 2. Initiate the Authorization Request
Construct the authorization request URL:

```
https://brightlever.app/oauth/authorize?response_type=token&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_ENCODED_REDIRECT_URI&scope=cms:read%20cms:write
```

**response_type:** Must be token for the Implicit Grant.

**client_id:** Your application's Client ID.

**redirect_uri:** Your application's encoded callback URI.

**scope:** (Optional) A space-delimited list of permissions your application requires. The available scopes are:
cms:read: Grants read-only access to content.
cms:write: Grants read and write access to content.
Redirect the user to this URL.

**state:** (Recommended) A random string to prevent cross-site request forgery (CSRF) attacks.

## 3. User Authorization and Token Retrieval
Brightlever will prompt the user to log in (if not already) and review the requested permissions.
If the user approves, Brightlever will redirect them back to your redirect_uri. The access token will be included in the URL fragment (#) of the redirect URI, along with the state parameter.
Example redirect URI:

```
https://your-app.com/callback#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=YOUR_RANDOM_STATE_STRING
```

## 4. Use the Access Token
Extract the access_token from the URL fragment and include it in the Authorization header of your API requests to Brightlever:

```
Authorization: Bearer ACCESS_TOKEN
```

#### Important Considerations
The Implicit Grant is less secure than the Authorization Code Grant, as the access token is exposed in the URL.
Consider using the Authorization Code Grant if your application has a backend server component.
Implement appropriate security measures to protect the access token in your client-side application.

OAuth2 - Implicit Grant

OAuth 2.0 Authorization Code Workflow for Brightlever Integration
This guide outlines the steps to integrate your application with Brightlever's APIs using the OAuth 2.0 authorization code grant type.

## 1. Register Your Application
Log in to the Brightlever and go to your environment admin.
Create a new application and provide the following information:
Application Name: A descriptive name for your application.
Redirect URI: The URI your application will redirect to after the user grants authorization (e.g., https://your-app.com/callback).
Upon successful registration, you'll receive a Client ID and Client Secret. Keep these confidential.

## 2. Initiate the Authorization Request
Construct the authorization request URL:

```
https://brightlever.app/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_ENCODED_REDIRECT_URI&scope=cms:read%20cms:write
```

**response_type:** Must be code for the authorization code grant.

**client_id:** Your application's Client ID.

**redirect_uri:** Your application's encoded callback URI.

**scope:** (Optional) A space-delimited list of permissions your application requires. The available scopes are:
cms:read: Grants read-only access to content.
cms:write: Grants read and write access to content.

**state:** (Recommended) A random string to prevent cross-site request forgery (CSRF) attacks.

## 3. User Authorization
Brightlever will prompt the user to log in (if not already) and review the requested permissions.
If the user approves, Brightlever will redirect them back to your redirect_uri with a temporary code and the state parameter in the query string.

## 4. Exchange Code for Access Token
Make a POST request to the Brightlever token endpoint:

```POST https://brightlever.app/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE_FROM_STEP_3
&redirect_uri=YOUR_ENCODED_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
```

Brightlever will respond with:

```
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "refresh_token": "REFRESH_TOKEN" 
}
```
Use code with caution.

```
access_token: Use this token in subsequent API requests to Brightlever.
refresh_token: (If requested) Used to obtain a new access token when the current one expires.
```

## 5. Use the Access Token
Include the access_token in the Authorization header of your API requests to Brightlever:

```
Authorization: Bearer ACCESS_TOKEN
```

## 6. Refresh the Access Token (Optional)
If you received a refresh_token, make a POST request to the token endpoint with grant_type=refresh_token to obtain a new access_token before it expires.


OAuth2 - Authorization Code

Learn about Brightlever's client libraries. Clean abstraction of the Brightlever API.

Client Libraries


Brightlever has a valuable Nodejs module that can be used to read and manage Brightlever data.
```
import Client, { Timestamp } from '@brightlever/client';

const client= new Client({
    environment_id:"YOUR_ENVIRONMENT_ID",
    access_token:"YOUR_ACCESS_TOKEN"
})

const response=await client
    .count()
    .sum('donation')
    .avg('age')
    .min('age')
    .max('age')
    .from('widget')
    .where('name','==','test')
    .orderBy('name','asc')
    .pageSize(100)
    .page(1)
    .get();

response.items.forEach(...)

const widget=await client.with('widget').id('asd').get();
const widget=await client.with('widget').id('asd').delete();
const widget=await client.with('widget').id('asd').rollback();
const widget=await client.with('widget').save(data);
const widget=await client.with('widget').publish(data);
const widget=await client.with('widget').validate(data);

const widgetStorage=client.with('widget').getStorage();

const newAssetMetadata=await widgetStorage.upload({
    file:file,
    overwrite:false
})

const assetMetadata=await await widgetStorage.metadata(newAssetMetadata.id)

const duplicatesMetadata=await await widgetStorage.duplicate(newAssetMetadata.id)

await await widgetStorage.delete(duplicatesMetadata.id)
```


When using the select method to explicitly pull specific document attributes you do not need to use the populate method. It automatically assumes that you want any selected relationships populated.

```
  const response=await client
    .select('name,address')
    .from('widget')
    .where('name','==','test')
    .orderBy('name','asc')
    .pageSize(100)
    .page(1)
    .get();
```

Otherwise you need to specifiy that you want any document relationships poplulated.

```
   const response=await client
    .from('widget')
    .where('name','==','test')
    .populate('address')
    .orderBy('name','asc')
    .pageSize(100)
    .page(1)
    .get();
```

Dates in Brightlever are store as objects with _seconds and _nanoseconds.

```
{
    _seconds:number
    _nanoseconds:number
}
```

So the node module supplies a Timestamp object that can be use to both serialize and deserialize native JS Date instances.

```
import Client, { Timestamp } from '@brightlever/client';

const blDateNow=Timestamp.fromDate(new Date());

const jsDateNow=Timestamp.toDate(blDateNow);

```



Node JS

Learn about webhooks and how you can create custom handlers to react to events with Brighlever.

Webhooks


You can create webhooks within your environments to listen for specific content management actions.

```
import express from 'express';

const app = express();

// SecretKey from Brighlever webhook definition
const secretKey='...'; 

const validatePayload=(payload,signature)=>{
    return (signature==crypto.createHmac("sha256", secretKey)
          .update(payload, "utf8")
          .digest("hex"))
}

// Important for Brightlever payloads
app.use(express.json({ type: 'application/*' }));

app.post('/webhook', (req, res) => {
    const payload = req.body;

    if(!validatePayload(payload,req.headers["x-brightlever-signature"])){
         res.sendStatus(500); 
    } else {
      
        console.log(`Webhook received: ${payload.action} event for ID ${payload.data._sys.id}`);
        console.log(`Webhook received: ${payload.sourceId} event source id`);
        // Your custom logic to process the event goes here

        res.sendStatus(200); 
    }  
});

app.listen(3000, () => console.log('Webhook server listening on port 3000'));
```

If you use webhooks to interact with the Brighlever api it is important to send the "X-Brightlever-Source-ID" header set to the sourceId that is in the webhook payload. 

This lets Brightlever know that the webhook handler doesn't need to be renotified about the update.

You can also register the source id with the node client module.

```
import Client from '@brightlever/client`;
import express from 'express';

const app = express();

// SecretKey from Brighlever webhook definition
const secretKey='...'; 

// API key generated from within the Brightlever environment admin.
const apiKey='...'; 

// Environment ID from Brightlever environment admin.
const environmentId='...'; 

const validatePayload=(payload,signature)=>{
    return (signature==crypto.createHmac("sha256", secretKey)
        .update(payload, "utf8")
        .digest("hex"))
}

// Important for Brightlever payloads
app.use(express.json({ type: 'application/*' }));

app.post('/webhook', async (req, res) => {
    const payload = req.body;

    if(!validatePayload(payload,req.headers["x-brightlever-signature"])){
         res.sendStatus(500); 
    } else {
        if(payload.data?._sys?.contentType=='widget'
            && !payload.data.enrichmentAttribute){
            
            const doc=payload.data;

            const client=new Client({
                environment_id:environmentId,
                access_token:apiKey,
                source_id:payload.sourceId
            });
     
            // Look update custom api to 
            // get enriched data attribute value.
            doc.enrichmentAttribute=await lookUpData();

            await client.with('widget)
                .id(doc.id)
                .save(doc);

            console.log(`Webhook handled.`)

        }

        res.sendStatus(200); 
    }  
});

app.listen(3000, () => console.log('Webhook server listening on port 3000'));
```

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    p: "p",
    strong: "strong",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "Access roles are used to create specific boundaries to what a user can do with their authticated connection to the Brightlever api. They are managed at the environment admin level."
    }), "\n", _jsx(_components.p, {
      children: "Per content type an access role can be assigned the following permissions:"
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Read.latest"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Read.published"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Doc.create"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Doc.update"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Doc.delete"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Doc.publish"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Schema.define"
      })
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};
