API Documentation

See the CMR Data Partner User Guide for a general guide to utilizing the CMR Ingest API as a data partner.
See the CMR Client Partner User Guide for a general guide to developing a CMR client.

Access Control API Overview


API Conventions

This defines conventions used across the Access Control API.

Headers

This defines common headers on the Access Control API.

Content-Type Header

Content-Type is a standard HTTP header that specifies the content type of the body of the request. Access Control only supports application/json as the representation type for data.

Authorization Header

All Access Control API operations require specifying a token.

An EDL token can be obtained from Earthdata Login (EDL). The token should be specified using the Authorization: Bearer header followed by the EDL bearer token. For more information on obtaining an EDL bearer token, please reference the documentation.

An example for generating a Launchpad token can he found on the Earthdata wiki. The token should be specified using the Authorization: header followed by the Launchpad token. More information on getting access to Launchpad tokens can be found on the Launchpad Authentication User's Guide.

Cmr-Revision-Id Header

The revision id header allows specifying the revision id to use when saving the concept. It is optional for all ACL updates. The update will be rejected when:

  1. The revision id specified is not an integer.
  2. The revision id specified <= current revision id of the acl - a HTTP Status code of 409 will be returned indicating a conflict.

Responses

Response Headers

cmr-request-id

This header returns the unique id assigned to the request. This can be used to help debug client errors. The value is a long string of the form

828ef0b8-a876-4579-85db-3cc9d1b5f6e5

HTTP Status Codes

Status Code Description
200 Success
400 Bad request. The body will contain errors.
404 Not found. This could be returned either because the URL isn't known by access control or the item wasn't found.
409 Conflict. This is returned when a revision id conflict occurred while saving the item.
415 Unsupported Media Type. The body will return an error message that contains the list of supported formats.
422 Unprocessable entity. Access control understood the request, but the concept failed ingest validation rules. The body will contain errors.
500 Internal error. Contact CMR Operations if this occurs.
503 Internal error because a service dependency is not available.

Successful Responses

Successful responses will return an HTTP Status code of 200 and a body containing the CMR Concept Id of the item that was updated or deleted along with the revision id.

{"concept_id":"AG12345-PROV","revision_id":1}

Access Control Lists (ACLs)

Access Control Lists (ACLs) define permissions within the CMR. Everything is restricted in the CMR by default. ACLs give permission to specific users to take some action on some data.

Every ACL defines three parts like a simple sentence: subject, predicate, and object. The sentence "Science Users can view Provider FOO's granules" is an example. "Science Users" is the subject. "can view" is the predicate. "Provider FOO's granules" is the object.

ACLs are represented by JSON. If "Science Users" was an existing group defined in Provider FOO with concept id AG1234-FOO then an ACL granting that group access to view and order and guests permission to view FOO's granules would look like the following:

{
    "group_permissions": [{
        "group_id": "AG1234-FOO",          // Subject
        "permissions": ["read", "order"]   // Predicates
    }, {
        "user_type": "guest",              // Subject
        "permissions": ["read"]            // Predicates
    }],
    "catalog_item_identity": {             // Object
        "name": "All Granules",
        "provider_id": "FOO",
        "granule_applicable": true
    }
}

This is like a sentence saying "Science Users can view and order and Guests can view Provider FOO's granules."

The subject and predicate are in group_permissions. An ACL can identify multiple permissions per group. There can be multiple subjects and multiple predicates per subject in a single ACL.

By default, any provided group_id must be in the format of a CMR group concept_id. If the access-control configuration allow-edl-groups is set to true, then this validation will be bypassed.

Every ACL refers to an object called an "identity". The "identity" identifies what in the CMR is being granted permission by the the ACL. There are 4 kinds of identities:

ACL Uniqueness

ACLs are uniquely identified by their identity. There can only be one ACL to a specific identity. For example provider identities contain a provider id (such as "Foo") and a target. There can only be one ACL in the system for granting permissions to Provider FOO's Option Definitions. The rules for uniquely identifying each type is listed below.

Create ACL

ACLs are created by POSTing a JSON representation of an ACL to https://cmr.earthdata.nasa.gov/access-control/acls along with a valid Launchpad token. The response will contain a concept id identifying the ACL along with the ACL revision id.

Creating an ACL

curl -XPOST -i -H "Content-Type: application/json" -H "Authorization: Bearer XXXX" https://cmr.earthdata.nasa.gov/access-control/acls -d \
'{
    "group_permissions": [{
        "group_id": "AG1234-FOO",
        "permissions": ["read", "order"]
    }, {
        "user_type": "guest",
        "permissions": ["read"]
    }],
    "catalog_item_identity": {
        "name": "All Granules",
        "provider_id": "FOO",
        "granule_applicable": true
    }
}'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1

{"revision_id":1,"concept_id":"ACL1200000000-CMR"}

Grantable Permissions

For system, provider, and single instance identities, the grantable permissions are limited by the target of the ACL.

System Identity

Target Grantable Permissions
SYSTEM_AUDIT_REPORT read
METRIC_DATA_POINT_SAMPLE read
SYSTEM_INITIALIZER create
ARCHIVE_RECORD delete
ERROR_MESSAGE update
TOKEN read, delete
TOKEN_REVOCATION create
EXTENDED_SERVICE_ACTIVATION create
ORDER_AND_ORDER_ITEMS read, delete
PROVIDER create, delete
TAG_GROUP create, update, delete
TAXONOMY create
TAXONOMY_ENTRY create
USER_CONTEXT read
USER read, update, delete
GROUP create, read
ANY_ACL create, read, update, delete
EVENT_NOTIFICATION delete
EXTENDED_SERVICE delete
SYSTEM_OPTION_DEFINITION create, delete
SYSTEM_OPTION_DEFINITION_DEPRECATION create
INGEST_MANAGEMENT_ACL read, update
SYSTEM_CALENDAR_EVENT create, update, delete
DASHBOARD_ADMIN create, read, update, delete
DASHBOARD_ARC_CURATOR create, read, update, delete
DASHBOARD_MDQ_CURATOR create, read, update, delete

Provider Identity

Target Grantable Permissions
AUDIT_REPORT read
OPTION_ASSIGNMENT create, read, delete
OPTION_DEFINITION create, delete
OPTION_DEFINITION_DEPRECATION create
DATASET_INFORMATION read
PROVIDER_HOLDINGS read
EXTENDED_SERVICE create, update, delete
PROVIDER_ORDER read
PROVIDER_ORDER_RESUBMISSION create
PROVIDER_ORDER_ACCEPTANCE create
PROVIDER_ORDER_REJECTION create
PROVIDER_ORDER_CLOSURE create
PROVIDER_ORDER_TRACKING_ID update
PROVIDER_INFORMATION update
PROVIDER_CONTEXT read
AUTHENTICATOR_DEFINITION create, delete
PROVIDER_POLICIES read, update, delete
USER read
GROUP create, read
PROVIDER_OBJECT_ACL create, read, update, delete
CATALOG_ITEM_ACL create, read, update, delete
INGEST_MANAGEMENT_ACL read, update
DATA_QUALITY_SUMMARY_DEFINITION create, update, delete
DATA_QUALITY_SUMMARY_ASSIGNMENT create, delete
PROVIDER_CALENDAR_EVENT create, update, delete
DASHBOARD_DAAC_CURATOR create, read, update, delete
NON_NASA_DRAFT_USER create, read, update, delete
NON_NASA_DRAFT_APPROVER create, read, update, delete
SUBSCRIPTION_MANAGEMENT read, update

Single Instance Identity

Target Grantable Permissions
GROUP_MANAGEMENT update, delete

Search ACLs

ACLs can be searched for by sending a GET request to https://cmr.earthdata.nasa.gov/access-control/acls, or a POST to https://cmr.earthdata.nasa.gov/access-control/acls/search. A valid EDL bearer token or Launchpad token is required to search ACLs. If no token is supplied then guest permissions are used.

ACL Search Parameters

The following parameters are supported when searching for ACLs.

Standard Parameters:
ACL Matching Parameters
ACL Search Response

The response is always returned in JSON and includes the following parts.

ACL Search Examples
By permitted_group
curl -i "https://cmr.earthdata.nasa.gov/access-control/acls/search" -d "permitted_group[]=guest&permitted_group[]=registered&pretty=true"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
CMR-Hits: 4
CMR-Took: 5
CMR-Request-Id: 5689303f-574d-4edf-b2f1-5219dc0ae6c5
Content-Length: 702

{
  "hits" : 3,
  "took" : 6,
  "items" : [ {
    "revision_id" : 1,
    "concept_id" : "ACL1200000008-CMR",
    "identity_type" : "Catalog Item",
    "name" : "All Collections",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000008-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000009-CMR",
    "identity_type" : "Catalog Item",
    "name" : "All Granules",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000009-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000006-CMR",
    "identity_type" : "Group",
    "name" : "Group - AG1234-CMR",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000006-CMR"
  } ]
}
By identity_type
curl -i "https://cmr.earthdata.nasa.gov/access-control/acls/search" -d "identity_type[]=provider&identity_type[]=catalog_item&pretty=true"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
CMR-Hits: 2
CMR-Took: 5
CMR-Request-Id: 5689303f-574d-4edf-b2f1-5219dc0ae6c5
Content-Length: 702

{
  "hits" : 2,
  "took" : 4,
  "items" : [ {
    "revision_id" : 1,
    "concept_id" : "ACL1200000003-CMR",
    "identity_type" : "Catalog Item",
    "name" : "All Collections",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000003-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000001-CMR",
    "identity_type" : "Provider",
    "name" : "Provider - PROV1 - AUDIT_REPORT",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000001-CMR"
  } ]
}
By permitted_user
curl -i "https://cmr.earthdata.nasa.gov/access-control/acls/search" -d "permitted_user=user1&pretty=true"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
CMR-Hits: 2
CMR-Took: 5
CMR-Request-Id: 5689303f-574d-4edf-b2f1-5219dc0ae6c5
Content-Length: 702

{
  "hits" : 2,
  "took" : 4,
  "items" : [ {
    "revision_id" : 1,
    "concept_id" : "ACL1200000003-CMR",
    "identity_type" : "Catalog Item",
    "name" : "All Collections",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000003-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000001-CMR",
    "identity_type" : "Provider",
    "name" : "Provider - PROV1 - AUDIT_REPORT",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000001-CMR"
  } ]
}
By provider
curl -i "https://cmr.earthdata.nasa.gov/access-control/acls/search" -d "provider=prov1&pretty=true"

HTTP/1.1 200 OK
Date: Thu, 28 Jul 2016 13:16:36 GMT
Content-Type: application/json; charset=UTF-8
Access-Control-Expose-Headers: CMR-Hits, CMR-Request-Id
Access-Control-Allow-Origin: *
CMR-Hits: 3
CMR-Took: 10
CMR-Request-Id: 04d273f9-c0c5-4f74-a788-00837d2b80f3
Content-Length: 688
Server: Jetty(9.2.10.v20150310)

{
  "hits" : 3,
  "took" : 10,
  "items" : [ {
    "revision_id" : 1,
    "concept_id" : "ACL1200000001-CMR",
    "identity_type" : "Catalog Item",
    "name" : "Catalog_Item1_PROV1",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000001-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000002-CMR",
    "identity_type" : "Catalog Item",
    "name" : "Catalog_Item2_PROV1",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000002-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000000-CMR",
    "identity_type" : "Provider",
    "name" : "Provider - PROV1 - INGEST_MANAGEMENT_ACL",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000000-CMR"
  } ]
}
By group_permission
curl -i "https://cmr.earthdata.nasa.gov/access-control/acls/search" -d "group_permission[0][permitted_group]=guest&group_permission[0][permission]=create&pretty=true"

HTTP/1.1 200 OK
Date: Fri, 12 Aug 2016 18:42:42 GMT
Content-Type: application/json; charset=UTF-8
Access-Control-Expose-Headers: CMR-Hits, CMR-Request-Id
Access-Control-Allow-Origin: *
CMR-Hits: 1
CMR-Took: 5
CMR-Request-Id: 987912b3-be19-43a2-84b7-0b768da36eec
Content-Length: 257
Server: Jetty(9.2.10.v20150310)

{
  "hits" : 1,
  "took" : 4,
  "items" : [ {
    "revision_id" : 1,
    "concept_id" : "ACL1200000002-CMR",
    "identity_type" : "System",
    "name" : "System - SYSTEM_AUDIT_REPORT",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000002-CMR"
  } ]
}
By permitted_concept_id
curl -i "https://cmr.earthdata.nasa.gov/access-control/acls/search" -d "permitted_concept_id=C1200000003-PROV1&pretty=true"

HTTP/1.1 200 OK
Date: Thu, 03 Nov 2016 15:48:41 GMT
Content-Type: application/json; charset=UTF-8
Access-Control-Expose-Headers: CMR-Hits, CMR-Request-Id
Access-Control-Allow-Origin: *
CMR-Hits: 2
CMR-Took: 21
CMR-Request-Id: 461bfb0f-dc52-442a-a79f-d615909298ac
Content-Length: 456
Server: Jetty(9.2.10.v20150310)

{
  "hits" : 2,
  "took" : 12,
  "items" : [ {
    "revision_id" : 1,
    "concept_id" : "ACL1200000008-CMR",
    "identity_type" : "Catalog Item",
    "name" : "Access value 1",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000008-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000007-CMR",
    "identity_type" : "Catalog Item",
    "name" : "Access value 1-10",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000007-CMR"
  } ]
}
With include_full_acl
curl -i "https://cmr.earthdata.nasa.gov/access-control/acls/search" -d "include_full_acl=true&pretty=true"

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
CMR-Hits: 2
CMR-Took: 27
CMR-Request-Id: b3e38b33-eaf3-46ac-9f04-fa62eabb2c11

{
  "hits" : 2,
  "took" : 27,
  "items" : [ {
    "revision_id" : 1,
    "concept_id" : "ACL1200000000-CMR",
    "identity_type" : "Provider",
    "acl" : {
      "group_permissions" : [ {
        "group_id" : "AG1200000003-PROV1",
        "permissions" : [ "delete", "update" ]
      } ],
      "provider_identity" : {
        "provider_id" : "PROV1",
        "target" : "INGEST_MANAGEMENT_ACL"
      }
    },
    "name" : "Provider - PROV1 - INGEST_MANAGEMENT_ACL",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000000-CMR"
  }, {
    "revision_id" : 1,
    "concept_id" : "ACL1200000002-CMR",
    "identity_type" : "Catalog Item",
    "acl" : {
      "group_permissions" : [ {
        "user_type" : "guest",
        "permissions" : [ "read" ]
      } ],
      "catalog_item_identity" : {
        "name" : "guest read acl",
        "provider_id" : "PROV1",
        "collection_applicable" : true
      }
    },
    "name" : "guest read acl",
    "location" : "https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000002-CMR"
  } ]
}

/acls/:acl-id

Retrieve ACL

A single ACL can be retrieved by sending a GET request to https://cmr.earthdata.nasa.gov/access-control/acls/<concept-id> where concept-id is the concept id of the ACL returned when it was created.

curl -i -H "Authorization: Bearer XXXX" https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000000-CMR?pretty=true

HTTP/1.1 200 OK
Content-Type: application/json

{
  "group_permissions" : [ {
    "group_id" : "AG1234-FOO",
    "permissions" : [ "read", "order" ]
  }, {
    "user_type" : "guest",
    "permissions" : [ "read" ]
  } ],
  "catalog_item_identity" : {
    "name" : "All Granules",
    "provider_id" : "FOO",
    "granule_applicable" : true
  }
}

Update ACL

An ACL can be updated by sending a PUT request to https://cmr.earthdata.nasa.gov/access-control/acls/<concept-id>, along with a valid Launchpad token, where concept-id is the concept id of the ACL returned when it was created. legacy-guid field cannot be modified during update. The fields that uniquely identify an ACL cannot be updated, e.g. the target field of a system identity ACL. This limitation will eventually be removed as documented in CMR-3163.

curl -XPUT -i -H "Authorization: Bearer XXXX" https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000000-CMR -d \
'{
    "group_permissions": [{
        "group_id": "AG1234-FOO",
        "permissions": ["read", "order"]
    }, {
        "user_type": "guest",
        "permissions": ["read"]
    }],
    "catalog_item_identity": {
        "name": "All Granules",
        "provider_id": "FOO",
        "granule_applicable": true
    }
}'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1

{"revision_id":2,"concept_id":"ACL1200000000-CMR"}

Delete ACL

An ACL can be deleted with a DELETE request to https://cmr.earthdata.nasa.gov/access-control/acls/<concept-id>, along with a valid Launchpad token, where concept-id is the concept id of the ACL returned when it was created.

curl -XDELETE -i -H "Authorization: Bearer XXXX" https://cmr.earthdata.nasa.gov/access-control/acls/ACL1200000000-CMR

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 50

{"revision-id":3,"concept-id":"ACL1200000000-CMR"}

Permisions

Checking User Permissions

You can check the permissions granted to a specific user or user type on specific concepts or system objects by making a GET request to https://cmr.earthdata.nasa.gov/access-control/permissions.

The response is a JSON object mapping target ids to arrays of permissions granted to the specified user for the respective concept.

Example GET request:

curl -g -i -H "Authorization: Bearer XXXX" "https://cmr.earthdata.nasa.gov/access-control/permissions?user_type=guest&concept_id[]=C1200000000-PROV1&concept_id[]=C1200000001-PROV1"

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1

{"C1200000000-PROV1": ["read"], "C1200000001-PROV1": []}

When requesting permissions for large sets of concept ids, you can make a POST request to https://cmr.earthdata.nasa.gov/access-control/permissions and pass the query parameters in URL encoded query string in the POST body.

Example POST request:

curl -i -XPOST -H "Content-Type: application/x-www-form-urlencoded" "https://cmr.earthdata.nasa.gov/access-control/permissions" -d \
  'user_type=guest&concept_id=C1200000003-PROV1&concept_id=C1200000004-PROV1'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1

"C1200000003-PROV1: ["read"], "C1200000004-PROV1": ["read"]}

Parameters

S3 Buckets

User Access to S3 Buckets

This endpoint will return a JSON list of S3 buckets a user has access to. If a list of providers is included in the request, the list of S3 buckets will be filtered to only include S3 buckets contained by collections within those providers.

Parameters

Example request:

curl -i -H "Authorization: Bearer XXXX" "https://cmr.earthdata.nasa.gov/access-control/s3-buckets?user_id=user1

HTTP/1.1 200 OK
Content-Length: 81
Content-Type: application/json

["s3","s3://aws.example-1.com","s3://aws.example-2.com","s3://aws.example-3.com"]

Example request with providers specified:

curl -i -H "Authorization: Bearer XXXX" "https://cmr.earthdata.nasa.gov/access-control/s3-buckets?user_id=user1&provider[]=PROV2&provider[]=PROV3

HTTP/1.1 200 OK
Content-Length: 51
Content-Type: application/json

["s3://aws.example-2.com","s3://aws.example-3.com"]

Health

Application Health

This will report the current health of the application. It checks all resources and services used by the application and reports their health status in the response body in JSON format. The report includes an "ok?" status and a "problem" field for each resource. The report includes an overall "ok?" status and health reports for each of a service's dependencies. It returns HTTP status code 200 when the application is healthy, which means all its interfacing resources and services are healthy; or HTTP status code 503 when one of the resources or services is not healthy. It also takes pretty parameter for pretty printing the response.

curl -i -XGET https://cmr.earthdata.nasa.gov/access-control/health?pretty=true

Example healthy response body:

{
  "echo" : {
    "ok?" : true
  },
  "metadata-db" : {
    "ok?" : true,
    "dependencies" : {
      "oracle" : {
        "ok?" : true
      },
      "echo" : {
        "ok?" : true
      }
    }
  }
}

Example unhealthy response body:

{
  "echo" : {
    "ok?" : true
  },
  "metadata-db" : {
    "ok?" : false,
    "dependencies" : {
      "oracle" : {
        "ok?" : false,
        "problem" : "Exception occurred while getting connection: oracle.ucp.UniversalConnectionPoolException: Cannot get Connection from Datasource: java.sql.SQLRecoverableException: IO Error: The Network Adapter could not establish the connection"
      },
      "echo" : {
        "ok?" : true
      }
    }
  }
}