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

post

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.

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

idstringRequired

The ID of the access token

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

createdAtstring · date-timeRequired

The date and time the access token was created

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

updatedAtstring · date-timeRequired

The date and time the access token was last updated

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

tokenstringRequired

The access token string

Example: crs_19c9bd530ccd3e1187eed12dc4edb70abe757fc4c7be9c5b

expiresAtstring · date-timeRequired

The date and time the access token expires

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

isActivebooleanRequired

Whether the access token is currently active

Example: true

permissionsobjectRequired

The permissions of the access token

Example: {"organization_info":"VIEW","organization_members":"VIEW","organization_projects":"VIEW","organization_inventory":"REQUEST","organization_warehouse":"WRITE"}

appIdstringRequired

The ID of the app associated with the access token

Example: 67890

post

/app/accessTokens

HTTPcURLJavaScriptPython

POST /app/accessTokens HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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

post

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

Path parameters

installationIdstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

idstringRequired

The ID of the access token

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

createdAtstring · date-timeRequired

The date and time the access token was created

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

updatedAtstring · date-timeRequired

The date and time the access token was last updated

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

tokenstringRequired

The access token string

Example: crs_19c9bd530ccd3e1187eed12dc4edb70abe757fc4c7be9c5b

expiresAtstring · date-timeRequired

The date and time the access token expires

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

isActivebooleanRequired

Whether the access token is currently active

Example: true

permissionsobjectRequired

The permissions of the access token

Example: {"organization_info":"VIEW","organization_members":"VIEW","organization_projects":"VIEW","organization_inventory":"REQUEST","organization_warehouse":"WRITE"}

appIdstringRequired

The ID of the app associated with the access token

Example: 67890

installationIdstringRequired

The ID of the installation associated with the access token

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

organizationIdstringRequired

The ID of the organization associated with the access token

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

post

/app/installations/{installationId}/accessTokens

HTTPcURLJavaScriptPython

POST /app/installations/{installationId}/accessTokens HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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

delete

This endpoint deletes the installation access token used to call it

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

booleanOptional

delete

/app/installations/token

HTTPcURLJavaScriptPython

DELETE /app/installations/token HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

true

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

get

This endpoint returns all active installation for an app

Query parameters

limitnumberRequired

The amount of items to return

Example: 10

pagenumberRequired

The page to return

Example: 0

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

get

/app/installations

HTTPcURLJavaScriptPython

GET /app/installations?limit=1&page=1 HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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

get

This endpoint returns a specific installation

Path parameters

installationIdstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

idstringRequired

The ID of the installation

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

createdAtstring · date-timeRequired

The creation date of the installation

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

updatedAtstring · date-timeRequired

The update date of the installation

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

permissionsobjectRequired

The permissions of the installation

Example: {"organization_info":"VIEW","organization_members":"VIEW","organization_projects":"VIEW","organization_inventory":"REQUEST","organization_warehouse":"WRITE"}

appNameIdstringRequired

The app name ID of the installation

Example: app1

appIdstringRequired

The app ID of the installation

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

accessTokensUrlstringRequired

The access tokens URL of the installation

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

get

/app/installations/{installationId}

HTTPcURLJavaScriptPython

GET /app/installations/{installationId} HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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