- Index - API Documentation
- Parameters - API Parameter Details
- Profiles - Manage user profiles
- Resources - Manage resources
- Rules - Manage the ACRs for resources
- EML - Manage EML documents and associated ACRs
- Groups - Manage groups and group members
- Search - Search for profiles and groups
- Tokens and API keys - Manage tokens and API keys
The EDI IAM implements a resource-based access control model where permissions are assigned to resources that represent real data, user actions and other objects in the EDI Data Repository, such as data packages, data entities, metadata documents, and access to upload new packages.
Each resource in the EDI IAM system acts as a security proxy for a real data entity. For example, a data package with identifier knb-lter-ntl.1.1 exists as actual data files in the repository, but it also has a corresponding tree of resource entries in the EDI IAM system. The resources hold the access control information that determines who can interact with the actual data and metadata in the package.
When a user attempts to access data or perform an action, the IAM system checks the ACRs on the corresponding resource. Access is granted only if an ACR exists that allows the requested operation for that user.
This model separates the actual data storage from the authorization logic. The data repository stores and serves data files, while the IAM system maintains a parallel structure of resources and permissions.
POST /auth/v1/resource
Create a resource for access control. A changePermission ACR is automatically added for the token profile, making the token profile the first owner of the resource. The token profile may then grant additional permissions via createRule().
Required permission: Caller must be in the Vetted system group.
| Parameter | In | Required | Description |
|---|---|---|---|
edi-token |
Cookie | Yes | See Parameters |
resource_key |
JSON body | Yes | Unique identifier for the resource |
resource_label |
JSON body | Yes | Human-readable name of the resource |
resource_type |
JSON body | Yes | Type of resource |
parent_resource_key |
JSON body | Yes | Resource key of the parent, or null for a top-level resource |
| Status | Description |
|---|---|
200 OK |
Resource created successfully |
400 Bad Request |
See Parameters; or a resource with the same key already exists |
401 Unauthorized |
See Parameters |
403 Forbidden |
Caller is not in the Vetted group |
200 OK response body:
| Field | Description |
|---|---|
method |
"createResource" |
msg |
"Resource created successfully" |
resource_key |
Resource key of the newly created resource |
Request:
curl -X POST https://auth.edirepository.org/auth/v1/resource \
-H "Cookie: edi-token=$(<~/Downloads/token-EDI-<my-token>.jwt)" \
-d '{
"resource_key": "https://pasta.lternet.edu/package/data/eml/edi/643/4/87c390495ad405e705c09e62ac6f58f0",
"resource_label": "edi.643.4",
"resource_type": "package",
"parent_resource_key": null
}'Response 200 OK (JSON):
{
"method": "createResource",
"msg": "Resource created successfully",
"resource_key": "https://pasta.lternet.edu/package/data/eml/edi/643/4/87c390495ad405e705c09e62ac6f58f0"
}Response 200 OK (XML):
<result>
<method>createResource</method>
<msg>Resource created successfully</msg>
<resource_key>https://pasta.lternet.edu/package/data/eml/edi/643/4/87c390495ad405e705c09e62ac6f58f0</resource_key>
</result>GET /auth/v1/authorized
Check if the requesting client has access to a resource at the specified permission level. Returns 200 OK if access is granted, 403 Forbidden if not.
| Parameter | In | Required | Description |
|---|---|---|---|
edi-token |
Cookie | Yes | See Parameters |
resource_key |
Query string | Yes | Unique identifier of the resource to check |
permission |
Query string | Yes | Permission level to check: read, write, or changePermission |
| Status | Description |
|---|---|
200 OK |
Caller has the requested permission on the resource |
401 Unauthorized |
See Parameters |
403 Forbidden |
Caller does not have the requested permission |
404 Not Found |
Resource not found |
GET /auth/v1/resource/<resource_key>
Return the resource associated with a resource key.
Required permission: Caller must have read permission on the resource.
| Parameter | In | Required | Description |
|---|---|---|---|
edi-token |
Cookie | Yes | See Parameters |
resource_key |
URL path | Yes | Unique identifier of the resource |
| Status | Description |
|---|---|
200 OK |
Resource retrieved successfully |
401 Unauthorized |
See Parameters |
403 Forbidden |
Caller does not have read permission |
404 Not Found |
Resource not found |
GET /auth/v1/resource-search
Search resources by regular expression on the resource key, label, and/or type. Returns only resources for which the caller has at least read permission. Uses Postgres regex syntax (~).
Required permission: Only resources on which the caller has at least read permission are returned.
| Parameter | In | Required | Description |
|---|---|---|---|
edi-token |
Cookie | Yes | See Parameters |
resource_key |
Query string | No | Regex pattern to match against resource key |
resource_label |
Query string | No | Regex pattern to match against resource label |
resource_type |
Query string | No | Regex pattern to match against resource type |
| Status | Description |
|---|---|
200 OK |
Search completed; response contains matching resources |
401 Unauthorized |
See Parameters |
403 Forbidden |
See Parameters |
GET /auth/v1/resource-tree/<resource_key>
Return the full tree to which the resource belongs. The tree includes the resource itself, its ancestors, and its descendants.
Required permission: Caller must have at least read permission on the resource.
| Parameter | In | Required | Description |
|---|---|---|---|
edi-token |
Cookie | Yes | See Parameters |
resource_key |
URL path | Yes | Unique identifier of the resource |
| Status | Description |
|---|---|
200 OK |
Resource tree retrieved successfully |
401 Unauthorized |
See Parameters |
403 Forbidden |
Caller does not have read permission |
404 Not Found |
Resource not found |
PUT /auth/v1/resource/<resource_key>
Update the attributes of a resource. If parent_resource_key is provided, this performs a "prune and graft" — the resource and all its descendants are moved to the new parent. Set parent_resource_key to null to move the resource to root level. If parent_resource_key is omitted, the parent is unchanged.
Required permission: Caller must have write permission on the resource. If parent_resource_key is being changed, caller must also have changePermission on both the new and current parent resources (if not null).
| Parameter | In | Required | Description |
|---|---|---|---|
edi-token |
Cookie | Yes | See Parameters |
resource_key |
URL path | Yes | Unique identifier of the resource to update |
resource_label |
JSON body | No | New human-readable name |
resource_type |
JSON body | No | New resource type |
parent_resource_key |
JSON body | No | New parent resource key, null to move to root, or omit to leave unchanged |
| Status | Description |
|---|---|
200 OK |
Resource updated successfully |
400 Bad Request |
See Parameters |
401 Unauthorized |
See Parameters |
403 Forbidden |
Caller lacks required permissions |
404 Not Found |
Resource not found |
DELETE /auth/v1/resource/<resource_key>
Delete a resource and all of its descendants recursively. All ACRs associated with the deleted resources are also automatically removed.
Required permission: Caller must have write permission on the resource and all descendant resources.
| Parameter | In | Required | Description |
|---|---|---|---|
edi-token |
Cookie | Yes | See Parameters |
resource_key |
URL path | Yes | Unique identifier of the resource to delete |
| Status | Description |
|---|---|
200 OK |
Resource and all descendants deleted successfully |
400 Bad Request |
See Parameters |
401 Unauthorized |
See Parameters |
403 Forbidden |
Caller lacks write permission on the resource or a descendant |
404 Not Found |
Resource not found |