Endpoints available for ICR apps

Your ICR 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 ICR.

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

Body

id*string

The ID of the access token

createdAt*string (date-time)

The date and time the access token was created

updatedAt*string (date-time)

The date and time the access token was last updated

token*string

The access token string

expiresAt*string (date-time)

The date and time the access token expires

isActive*boolean

Whether the access token is currently active

permissions*object

The permissions of the access token

appId*string

The ID of the app associated with the access token

Request

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

Response

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

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

Body

id*string

The ID of the access token

createdAt*string (date-time)

The date and time the access token was created

updatedAt*string (date-time)

The date and time the access token was last updated

token*string

The access token string

expiresAt*string (date-time)

The date and time the access token expires

isActive*boolean

Whether the access token is currently active

permissions*object

The permissions of the access token

appId*string

The ID of the app associated with the access token

installationId*string

The ID of the installation associated with the access token

organizationId*string

The ID of the organization associated with the access token

Request

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

Response

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

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

Body

boolean

Request

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

Response

false

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

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'

create user and organization

Create a user and an organization

This endpoint creates a user and organization where the user is admin. The app is also default installed on the organization.

POSThttps://api.carbonregistry.com/app/create/user/organization

Authorization

Header parameters

Body

user*all of

The user to be created

organization*all of

The organization to be created

Response

Body

id*string

The ID of the installation

createdAt*string (date-time)

The creation date of the installation

updatedAt*string (date-time)

The update date of the installation

organization*all of

The organization of the installation

permissions*object

The permissions of the installation

appNameId*string

The app name ID of the installation

appId*string

The app ID of the installation

accessTokensUrl*string

The access tokens URL of the installation

Request

const response = await fetch('https://api.carbonregistry.com/app/create/user/organization', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer Bearer",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "user": {
        "email": "john@gmail.com",
        "fullName": "John Doe",
        "profilePicture": "text"
      },
      "organization": {
        "fullName": "Organization 1",
        "type": "other",
        "countryCode": "US"
      }
    }),
});
const data = await response.json();

Response

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

This endpoint allows an app to create a user and an organization under that user. The resulting organization has the app auto installed. This can be useful if a user of an app's website is interacting with credits on ICR but does not have an organization themselves then the app can create a user on ICR for him and an organization. Can especially be useful when finishing a purchase of credits, then the receiver of the credits must be an organization. In this case the marketplace can create the user / organization and deposit the credits there where the end user can claim them at a later date.

curl -X 'POST' \
  'https://api.carbonregistry.com/app/create/user/organization' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_JWT"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "user": {
    "email": "john@gmail.com",
    "fullName": "John Doe",
    "profilePicture": ""
  },
  "organization": {
    "fullName": "Organization 1",
    "type": "other",
    "countryCode": "US"
  }
}'

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

Body

pagination*ApiPaginationDto (object)

installations*array of ApiInstallationDto (object)

Request

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

Response

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

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

Body

id*string

The ID of the installation

createdAt*string (date-time)

The creation date of the installation

updatedAt*string (date-time)

The update date of the installation

organization*all of

The organization of the installation

permissions*object

The permissions of the installation

appNameId*string

The app name ID of the installation

appId*string

The app ID of the installation

accessTokensUrl*string

The access tokens URL of the installation

Request

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

Response

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

PreviousEndpoints NextEndpoints available for ICR App installation and Organization access tokens

Last updated 3 months ago

const response = await fetch('https://api.carbonregistry.com/app/create/user/organization', { method: 'POST', headers: { "Authorization": "Bearer Bearer", "Content-Type": "application/json" }, body: JSON.stringify({ "user": { "email": "john@gmail.com", "fullName": "John Doe", "profilePicture": "text" }, "organization": { "fullName": "Organization 1", "type": "other", "countryCode": "US" } }), }); const data = await response.json();

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