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.
Join the CMR Client Developer Forum to ask questions, make suggestions and discuss topics like future CMR capabilities.

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.

Echo-Token Header

All Access Control API operations require specifying a token obtained from URS or ECHO. The token should be specified using the Echo-Token header.

Authorization Header

The token can alternatively be specified using the Authorization: Bearer header, and by specifying a Bearer token.

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 update. 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}

Groups

Groups are used to identify sets of users for the assignment of access privileges. Groups are either owned by a provider or the system. Provider level groups define sets of users access to that providers data. System level groups define sets of users for assigning system level access. Groups have the following fields:

Create Group

Groups are created by POSTing a JSON representation of a group to https://cmr.earthdata.nasa.gov/access-control/groups along with a valid ECHO token. Optionally, a managing_group_id parameter can be used to specify the managing group of the newly created group; Its value is the concept id of the existing group that will able to update or delete the new group. The response will contain a concept id identifying the group along with the group revision id. Creating and updating a group is synchronous and the group will be visible in search immediately after the ingest response is returned.

Creating a System Level Group

curl -XPOST -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.earthdata.nasa.gov/access-control/groups -d \
'{
  "name": "Administrators",
  "description": "The group of users that manages the CMR.",
  "members": ["user1", "user2"]
 }'

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

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

Creating a Provider Level Group

curl -XPOST -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.earthdata.nasa.gov/access-control/groups -d \
'{
  "name": "Administrators",
  "provider_id": "PROV1",
  "description": "The group of users that manages PROV1s data holdings."
 }'

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

{"revision_id":1,"concept_id":"AG1200000001-PROV1"}

Retrieve Group

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

curl -i -H "Echo-Token: XXXX" https://cmr.earthdata.nasa.gov/access-control/groups/AG1200000000-CMR?pretty=true

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

{
  "name" : "Administrators",
  "description" : "The group of users that manages PROV1s data holdings."
}

Update Group

Groups are updated by sending a PUT request with the JSON representation of a group to https://cmr.earthdata.nasa.gov/access-control/groups/<concept-id> where concept-id is the concept id of the group returned when it was created. The same rules apply when updating a group as when creating it but only the description can be modified. The response will contain the concept id along with the group revision id.

Only keys present in the update request will be updated. For example: if a "members" key is specified, then the group's members will be updated with the supplied value, otherwise the group's members will remain unchanged.

curl -XPUT -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.earthdata.nasa.gov/access-control/groups/AG1200000000-CMR -d \
'{
  "name": "Administrators",
  "description": "The group of users that manages the CMR and related systems."
 }'

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

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

Delete Group

Groups are deleted by sending a DELETE request to https://cmr.earthdata.nasa.gov/access-control/groups/<concept-id> where concept-id is the concept id of the group returned when it was created. Deleting a group creates a tombstone that marks the group as deleted. The concept id of the group and the revision id of the tombstone are returned from a delete request.

curl -XDELETE -i  -H "Echo-Token: XXXXX" https://cmr.earthdata.nasa.gov/access-control/groups/AG1200000000-CMR

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

{"concept_id":"AG1200000000-CMR","revision_id":3}

Retrieve Group Members

The members in a group can be retrieved by sending a GET request to https://cmr.earthdata.nasa.gov/access-control/groups/<concept-id>/members where concept-id is the concept id of the group returned when it was created.

curl -i -H "Echo-Token: XXXX" https://cmr.earthdata.nasa.gov/access-control/groups/AG1200000000-CMR/members?pretty=true

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

["user1", "user2", "user3"]

Add Group Members

The members in a group can be added by sending a POST request to https://cmr.earthdata.nasa.gov/access-control/groups/<concept-id>/members where concept-id is the concept id of the group returned when it was created. The body of the request should be a JSON array of Earthdata Login usernames. The concept id and updated revision number is returned.

curl -i -XPOST -H "Echo-Token: XXXX" -H "Content-Type: application/json" https://cmr.earthdata.nasa.gov/access-control/groups/AG1200000000-CMR/members -d
'["user1", "user2", "user3"]'

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

{"concept_id":"AG1200000000-CMR","revision_id":3}

Remove Group Members

The members in a group can be removed by sending a DELETE request to https://cmr.earthdata.nasa.gov/access-control/groups/<concept-id>/members where concept-id is the concept id of the group returned when it was created. The body of the request should be a JSON array of Earthdata Login usernames to remove. The concept id and updated revision number is returned.

curl -i -XDELETE -H "Echo-Token: XXXX" -H "Content-Type: application/json" https://cmr.earthdata.nasa.gov/access-control/groups/AG1200000000-CMR/members -d
'["user1", "user2", "user3"]'

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

{"concept_id":"AG1200000000-CMR","revision_id":4}

Search Groups

Groups can be searched for by sending a GET request to https://cmr.earthdata.nasa.gov/access-control/groups

Group Search Parameters

The following parameters are supported when searching for groups.

Standard Parameters:
Group Matching Parameters

These parameters will match fields within a group. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of provider[]=PROV1&provider[]=PROV2.

Group Search Response

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

Group Search Example
curl -i https://cmr.earthdata.nasa.gov/access-control/groups?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" : 4,
  "took" : 5,
  "items" : [ {
    "member_count" : 2,
    "name" : "Administrators",
    "description" : "na",
    "revision_id" : 2,
    "concept_id" : "AG1200000002-PROV1",
    "provider_id" : "PROV1"
  }, {
    "name" : "Administrators",
    "member_count" : 2,
    "description" : "na",
    "revision_id" : 2,
    "concept_id" : "AG1200000000-CMR"
  }, {
    "name" : "Data Readers",
    "member_count" : 2,
    "description" : "na",
    "revision_id" : 2,
    "concept_id" : "AG1200000001-CMR"
  } ]
}

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 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 ECHO 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 "Echo-Token: XXXXX" 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 Echo 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"
  } ]
}

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.

Search parameter include_legacy_group_guid, which is a boolean parameter, can be used to indicate if legacy group guid should be returned in place of group concept id in the returned ACL.

curl -i -H "Echo-Token: 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> 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 "Echo-Token: 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> where concept-id is the concept id of the ACL returned when it was created.

curl -XDELETE -i -H "Echo-Token: mock-echo-system-token" 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"}

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

curl -g -i -H "Echo-Token: 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": []}

Parameters

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 "Echo-Token: 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 "Echo-Token: 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"]

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