Apps

Your App can make requests to the following REST endpoints with an App signed JWT.

Who can use these endpoints

You need to use a JWT to access these endpoints using your ICR App's private key to sign it. For more information, see "Authenticating as an ICR App."

Access tokens

Access tokens are how your app gets access to organization and credit resources on CarbonRegistry.com.

app access token

Generate an app access token

This endpoint generates an app access token. This access token can be used to access app specific resources and general "public" resources, like the /projects endpoint.

POSThttps://api.carbonregistry.com/app/accessTokens

Header parameters

Response

200

Body

application/json

id*string

The ID of the access token

Example: "123e4567-e89b-12d3-a456-426614174000"

createdAt*string (date-time)

The date and time the access token was created

Example: "2022-01-01T00:00:00Z"

updatedAt*string (date-time)

The date and time the access token was last updated

Example: "2022-01-01T00:00:00Z"

token*string

The access token string

Example: "crs_19c9bd530ccd3e1187eed12dc4edb70abe757fc4c7be9c5b"

expiresAt*string (date-time)

The date and time the access token expires

Example: "2022-02-01T00:00:00Z"

isActive*boolean

Whether the access token is currently active

Example: true

permissions*object

The permissions of the access token

appId*string

The ID of the app associated with the access token

Example: "67890"

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/app/accessTokens', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "token": "crs_19c9bd530ccd3e1187eed12dc4edb70abe757fc4c7be9c5b",
  "expiresAt": "2022-02-01T00:00:00Z",
  "isActive": true,
  "permissions": {
    "organization_info": "VIEW",
    "organization_members": "VIEW",
    "organization_projects": "VIEW",
    "organization_inventory": "REQUEST",
    "organization_warehouse": "WRITE"
  },
  "appId": "67890"
}

The app access token is an access token you can use if you do not need to make requests accessing organization resources. This is mostly for semi-public endpoints like getting information on public projects.

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/app/accessTokens' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_JWT"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

installation access token

Generate an installation access token

This endpoint generates an installation access token for a specific installation. This access token can be used to access organization resources.

POSThttps://api.carbonregistry.com/app/installations/{installationId}/accessTokens

Path parameters

installationId*string

Header parameters

Response

200

Body

application/json

id*string

The ID of the access token

Example: "123e4567-e89b-12d3-a456-426614174000"

createdAt*string (date-time)

The date and time the access token was created

Example: "2022-01-01T00:00:00Z"

updatedAt*string (date-time)

The date and time the access token was last updated

Example: "2022-01-01T00:00:00Z"

token*string

The access token string

Example: "crs_19c9bd530ccd3e1187eed12dc4edb70abe757fc4c7be9c5b"

expiresAt*string (date-time)

The date and time the access token expires

Example: "2022-02-01T00:00:00Z"

isActive*boolean

Whether the access token is currently active

Example: true

permissions*object

The permissions of the access token

appId*string

The ID of the app associated with the access token

Example: "67890"

installationId*string

The ID of the installation associated with the access token

Example: "123e4567-e89b-12d3-a456-426614174000"

organizationId*string

The ID of the organization associated with the access token

Example: "123e4567-e89b-12d3-a456-426614174000"

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/app/installations/{installationId}/accessTokens', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "token": "crs_19c9bd530ccd3e1187eed12dc4edb70abe757fc4c7be9c5b",
  "expiresAt": "2022-02-01T00:00:00Z",
  "isActive": true,
  "permissions": {
    "organization_info": "VIEW",
    "organization_members": "VIEW",
    "organization_projects": "VIEW",
    "organization_inventory": "REQUEST",
    "organization_warehouse": "WRITE"
  },
  "appId": "67890",
  "installationId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000"
}

Installation access tokens are the tokens you need when accessing resources from organizations. These tokens are needed when making requests to the "Endpoints available for ICR App installations".

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/app/installations/{INSTALLATION_ID}/accessTokens' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_JWT"\
  -H 'x-icr-api-version: 2023-06-16' 

Typescript

delete access token

Delete an installation access token

This endpoint deletes the installation access token used to call it

DELETEhttps://api.carbonregistry.com/app/installations/token

Header parameters

Response

200

Body

application/json

boolean

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/app/installations/token', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

200

false

Enables deleting / invalidating an access token. It invalidates the one used in the authorization header.

cURL

curl -X 'DELETE' \
  'https://api.carbonregistry.com/app/installations/token' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

all app installations

Get all installations for an app

This endpoint returns all active installation for an app

GEThttps://api.carbonregistry.com/app/installations

Query parameters

Header parameters

Response

200

Body

application/json

pagination*ApiPaginationDto (object)

installations*array of ApiInstallationDto (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/app/installations?limit=0&page=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "pagination": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  },
  "installations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2022-01-01T00:00:00Z",
      "updatedAt": "2022-01-01T00:00:00Z",
      "organization": {
        "createdAt": "2022-01-01T00:00:00Z",
        "updatedAt": "2022-01-01T00:00:00Z",
        "fullName": "Organization 1",
        "countryCode": "US",
        "city": "New York",
        "zip": "10001",
        "physicalAddress": "123 Main St",
        "registrationNumber": "123456",
        "website": "http://example.com",
        "logo": "logo.png",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "organizationIndustries": {
          "code": "IND1",
          "name": "Industry 1"
        },
        "type": "projectProponent",
        "isPublic": true,
        "url": "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000"
      },
      "permissions": {
        "organization_info": "VIEW",
        "organization_members": "VIEW",
        "organization_projects": "VIEW",
        "organization_inventory": "REQUEST",
        "organization_warehouse": "WRITE"
      },
      "appNameId": "app1",
      "appId": "123e4567-e89b-12d3-a456-426614174000",
      "accessTokensUrl": "https://api.carbonregistry.com/app/installations/123e4567-e89b-12d3-a456-426614174000/accessTokens"
    }
  ]
}

A paginated list of all app installations for this app.

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/app/installations?limit=10&page=0' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_JWT"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

specific app installation

Get an installation

This endpoint returns a specific installation

GEThttps://api.carbonregistry.com/app/installations/{installationId}

Path parameters

installationId*string

Header parameters

Response

200

Body

application/json

id*string

The ID of the installation

Example: "123e4567-e89b-12d3-a456-426614174000"

createdAt*string (date-time)

The creation date of the installation

Example: "2022-01-01T00:00:00Z"

updatedAt*string (date-time)

The update date of the installation

Example: "2022-01-01T00:00:00Z"

organization*all of

The organization of the installation

permissions*object

The permissions of the installation

appNameId*string

The app name ID of the installation

Example: "app1"

appId*string

The app ID of the installation

Example: "123e4567-e89b-12d3-a456-426614174000"

accessTokensUrl*string

The access tokens URL of the installation

Example: "https://api.carbonregistry.com/app/installations/123e4567-e89b-12d3-a456-426614174000/accessTokens"

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/app/installations/{installationId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "organization": {
    "createdAt": "2022-01-01T00:00:00Z",
    "updatedAt": "2022-01-01T00:00:00Z",
    "fullName": "Organization 1",
    "countryCode": "US",
    "city": "New York",
    "zip": "10001",
    "physicalAddress": "123 Main St",
    "registrationNumber": "123456",
    "website": "http://example.com",
    "logo": "logo.png",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organizationIndustries": {
      "code": "IND1",
      "name": "Industry 1"
    },
    "type": "projectProponent",
    "isPublic": true,
    "url": "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000"
  },
  "permissions": {
    "organization_info": "VIEW",
    "organization_members": "VIEW",
    "organization_projects": "VIEW",
    "organization_inventory": "REQUEST",
    "organization_warehouse": "WRITE"
  },
  "appNameId": "app1",
  "appId": "123e4567-e89b-12d3-a456-426614174000",
  "accessTokensUrl": "https://api.carbonregistry.com/app/installations/123e4567-e89b-12d3-a456-426614174000/accessTokens"
}

Returns a specific app installation.

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/app/installations/{INSTALLATION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_JWT"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript