CMR Access Control - API Documentation

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

/groups
- POST - Create Group
- GET - Search Groups
/groups/:group-id
/groups/:group-id/members
/acls
- POST - Create ACL
- GET - Search ACLs
/acls/:acl-id
/permissions
- GET - Check User Permissions
/s3-buckets
- GET - Check User Permissions to S3 Buckets
/health
- GET - Get the health of the access control application.

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:

name - Required field that uniquely identifies a system group or a group within a provider.
provider_id - Id of the provider that owns the group. If this isn't present then the group will be a system level group.
description - Required field that describes the group.
members - Optional. May be specified in create and update operations.
legacy_guid - Internal use only. This is used for ECHO Kernel interoperability.

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:

page_size
page_num
pretty
include_members - boolean parameter that indicates if the members of the group should be returned.

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.

provider
options: ignore_case, pattern
This allows searching for either system level groups or groups owned by a specific provider. Use the provider id of "CMR" to search for system level groups.
name
options: ignore_case, pattern
legacy_guid
options: ignore_case, pattern
member
options: pattern, and
Allows searching for groups by member. The Earthdata Login username should be provided. It is always searched case-insensitively.
The and option allows specifying when sending multiple members whether to find groups that contain at least one of the members passed in (options[member][and]=false) or all of the members passed in (options[member][and]=true). The option defaults to false.
concept_id - matches group concept ids

Group Search Response

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

hits - How many total groups were found.
took - How long the search took in milliseconds
items - a list of the current page of groups with the following fields
concept_id
revision_id
name
description
provider_id - if a provider level group
member_count - The number of users in the group

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.

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:

System Identities - Identifies a system level thing in the CMR.
Provider Identities - Identifies a type of object owned by a specific provider.
Single Instance Identities - Identifies a single instance of something in the CMR. Currently this only applies to managing specific groups.
Catalog Item Identities - Identifies sets of catalog items (collections and granules) owned by a provider.

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.

System Identities - Unique by target
Provider Identities - Unique by provider id and target
Single Instance Identities - Unique by target id (Group concept id)
Catalog Item Identities - Unique by provider id and name.

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:

page_size
page_num
pretty
include_full_acl - boolean parameter that indicates if the full acl details should be included in the search response.
include_legacy_group_guid - boolean parameter that indicates if legacy group guid should be returned in place of group concept id in full acl search response. It can only be used when include_full_acl parameter is true.

ACL Matching Parameters

permitted_group
options: ignore_case
identity_type
options: none (always case-insensitive)
The type must be one or more of the following
- system
- provider
- single_instance
- catalog_item
target
options: none (always case-insensitive)
Matches ACLs which have the given object identity target
target_id
options: none (case-sensitive)
Matches single_instance ACLs through specified group target_id. Only applies when the single_instance target is GROUP_MANAGEMENT
identity_type=single_instance parameter is required alongside this parameter
permitted_user
options: none (always case-insensitive)
user is a URS user name corresponding to a member of a group that has access to an ACL
provider
options: ignore_case
Matches ACLs which reference a provider through a catalog item identity or a provider identity
group_permission
options: none (always case-insensitive)
This is a nested parameter that has subfields 'permitted_group' and 'permission'; it can contain both subfields or just one
permitted_concept_id
Matches ACLs that grant permission to the collection or granule with the given concept id
For an ACL to grant permission to a collection, the collection_applicable field of the ACL should be true and all the collection identifier filters (entry title, temporal and access value) of the ACL should match the related fields of the collection; no collection identifier defined in the ACL makes the ACL match all collections when its collection_applicable field is true.
For an ACL to grant permission to a granule, the granule_applicable field of the ACL should be true and both the granule identifier filters (temporal and access value), and collection identifier filters (entry title, temporal and access value) of the ACL should match the related fields of the granule and its parent collection.
id
options: none (case-sensitive)
Matches either ACL concept ID or ACL legacy GUID

ACL Search Response

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

hits - How many total ACLs were found.
took - How long the search took in milliseconds
items - a list of the current page of ACLs with the following fields
concept_id
revision_id
name - This will be the catalog item identity name or a string containing " - ". For example "System - PROVIDER"
identity_type - String of "provider", "system", "single_instance", or "catalog_item"
location - A URL to retrieve the ACL
acl - full JSON of the ACL. Included if include_full_acl=true parameter is set.

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

One of:
concept_id - Must be a valid concept id, or else use concept_id[]=...&concept_id[]=... to specify multiple concepts.
system_object - A system object identity target, e.g. "GROUP"
provider AND target - A provider id and a provider object identity target, e.g. "PROVIDER_HOLDINGS"
target_group_id - A single instance object identity target id, i.e. group concept id
And one of:
user_id - The user whose permissions will be computed.
user_type - Either "guest" or "registered".

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

Required:
user_id - The user whose available S3 buckets and object prefix names will be determined for.
Optional
provider[] - A list of provider ids to filter the S3 bucket and object prefix names by. If not specified, all providers will be included.

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