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

post

/app/accessTokens

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

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

post

/app/installations/{installationId}/accessTokens

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

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

Responseboolean

delete

/app/installations/token

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

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

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

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

get

/app/installations/{installationId}

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

PreviousV0.5 NextOrganizations

Last updated 1 year ago