4. API

The provisioning API is available through HTTP calls. Authentication is handled by JSON Web Tokens (JWT) for all calls except permission_responses. Both the DAS and the calling application need to know a shared secret, JWT_SECRET_KEY in the configuration file.

The following JWT attributes need to be present in the payload:

{
  "iss": "mgrid",
  "iat": 1532007679,
  "jti": "9deb0180-8a0f-4c12-b6d4-1841d357f04b",
  "identity": "name_of_calling_application",
  "type": "access",
  "fresh": "True"
}

Where iat is the number of seconds since epoch and jti is a nonce, e.g. a UUID.

This payload then needs to be signed with the shared secret and added as the Authorization HTTP header. In a Python program this can be performed as such:

token = jwt.encode(payload, jwt_secret_key, algorithm="HS512")
http_header = {"Authorization": "Bearer %s" % token}

4.1. Datasets

4.1.1. /api/v1/datasets GET

List all known datasets.

Input: None

Output

 [
   {
     "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
     "name": "dataset1",
     "id": 1
   },
   {
     "uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
     "name": "dataset2",
     "id": 2
   }
]

4.1.2. /api/v1/datasets POST

Create a new dataset. Note that uuid must be unique among all datasets.

Input

{
  "name": "dataset1",
  "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c"
}

Output

{
  "name": "dataset1",
  "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
  "id": 1
}

4.1.3. /api/v1/datasets/{id} GET

List a specific dataset by identifier.

Input: Dataset identifier in the URL

Output

{
  "name": "dataset1",
  "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
  "id": 1
}

4.1.4. /api/v1/datasets/{id} DELETE

Delete a specific dataset by identifier.

Input: Dataset identifier in the URL

Output

{
  "code": 200,
  "status": "Deleted",
  "message": "Dataset successfully deleted"
}

4.1.5. /api/v1/datasets/by_uuid/{uuid} GET

List a specific dataset by UUID.

Input: UUID in the URL

Output

{
  "name": "dataset1",
  "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
  "id": 1
}

4.2. Users

4.2.1. /api/v1/users GET

List all known users.

Input: None

Output

[
  {
    "email": "user1@example.com",
    "name": "user1",
    "id": 1
  },
  {
    "email": "user2@example.com",
    "name": "user2",
    "id": 2
  }
]

4.2.2. /api/v1/users POST

Create a new user. Note that email must be unique among all users.

Input

{
  "name": "user1",
  "email": "user1@example.com"
}

Output

{
  "name": "user1",
  "email": "user1@example.com",
  "id": 1
}

4.2.3. /api/v1/users/{id} GET

List a specific user by identifier.

Input: User identifier in the URL

Output

{
  "email": "user1@example.com",
  "name": "user1",
  "id": 1
}

4.2.4. /api/v1/users/{id} DELETE

Delete a specific user by identifier.

Input: User identifier in the URL

Output

{
  "code": 200,
  "status": "Deleted",
  "message": "User successfully deleted"
}

4.2.5. /api/v1/users/by_email/{email} GET

List a specific user by email address.

Input: Email address in the URL

Output

{
  "email": "user1@example.com",
  "name": "user1",
  "id": 1
}

4.3. Approvers

4.3.1. /api/v1/approvers GET

List all known approvers.

Input: None

Output

[
  {
    "operation": "view",
    "dataset": {
      "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
      "name": "dataset1",
      "id": 1
    },
    "user": {
      "email": "user1@example.com",
      "name": "user1",
      "id": 1
    },
    "id": 1
  },
  {
    "operation": "transfer",
    "dataset": {
      "uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
      "name": "dataset2",
      "id": 2
    },
    "user": {
      "email": "user1@example.com",
      "name": "user1",
      "id": 1
    },
    "id": 2
  }
]

4.3.2. /api/v1/approvers POST

Create a new approver.

Input

{
  "dataset_id": 2,
  "user_id": 1,
  "operation": "transfer"
}

Output

{
  "operation": "transfer",
  "dataset": {
    "uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
    "name": "dataset2",
    "id": 2
  },
  "user": {
    "email": "user1@example.com",
    "name": "user1",
    "id": 1
  },
  "id": 2
}

4.3.3. /api/v1/approvers/{id} GET

List a specific approver by identifier.

Input: Approver identifier in the URL

Output

{
  "operation": "transfer",
  "dataset": {
    "uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
    "name": "dataset2",
    "id": 2
  },
  "user": {
    "email": "user1@example.com",
    "name": "user1",
    "id": 1
  },
  "id": 2
}

4.3.4. /api/v1/approvers/{id} DELETE

Delete a specific approver by identifier.

Input: Approver identifier in the URL

Output

{
  "code": 200,
  "status": "Deleted",
  "message": "Approver successfully deleted"
}

4.4. Authorisations

4.4.1. /api/v1/authorisations GET

List all known authorisations.

Input: None

Output

[
  {
    "dataset": {
      "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
      "name": "dataset1",
      "id": 4
    },
    "context": "123456789",
    "operation": "transfer",
    "user": {
      "email": "user1@example.com",
      "name": "user1",
      "id": 6
    },
    "id": 2
  }
]

4.4.2. /api/v1/authorisations POST

Create a new authorisation.

Input

{
  "dataset_id": 2,
  "user_id": 1,
  "operation": "transfer",
  "context": "123456789"
}

Output

{
  "operation": "transfer",
  "dataset": {
    "uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
    "name": "dataset2",
    "id": 2
  },
  "user": {
    "email": "user1@example.com",
    "name": "user1",
    "id": 1
  },
  "context": "123456789",
  "id": 2
}

4.4.3. /api/v1/authorisations/{id} GET

List a specific authorisation by identifier.

Input: Authorisation identifier in the URL

Output

{
  "operation": "transfer",
  "dataset": {
    "uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
    "name": "dataset2",
    "id": 2
  },
  "user": {
    "email": "user1@example.com",
    "name": "user1",
    "id": 1
  },
  "id": 2
}

4.4.4. /api/v1/authorisations/{id} DELETE

Delete a specific authorisation by identifier.

Input: Authorisation identifier in the URL

Output

{
  "code": 200,
  "status": "Deleted",
  "message": "Authorisation successfully deleted"
}

4.5. Permission Requests

4.5.1. /api/v1/permission_requests GET

List all known permission requests.

Input: None

Output

[
  {
    "denied_message": "Message shown to user if request is denied",
    "operation": "transfer",
    "user": {
      "id": 1,
      "email": "user1@example.com",
      "name": "user1"
    },
    "details": {"reason": "Details of the permission prequest"},
    "approved_message": "Message shown to user if request is approved",
    "dataset": {
      "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
      "id": 1,
      "name": "dataset1"
    },
    "context": "123456789",
    "id": 2,
    "approved": false,
    "denied": false
  }
]

4.5.2. /api/v1/permission_requests POST

Create a new permission request.

Input

{
  "user_email": "user1@example.com",
  "operation": "transfer",
  "dataset_uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
  "details": {"reason": "Details of the permission request"},
  "approved_message": "Message shown to user if request is approved",
  "denied_message": "Message shown to user if request is denied",
  "context": "123456789"
}

Output

{
  "id": 2
}

4.5.3. /api/v1/permission_requests/{id} GET

List a specific permission request by identifier.

Input: Permission request identifier in the URL

Output

{
  "denied_message": "Message shown to user if request is denied",
  "operation": "transfer",
  "user": {
    "id": 1,
    "email": "user1@example.com",
    "name": "user1"
  },
  "details": {"reason": "Details of the permission request"},
  "approved_message": "Message shown to user if request is approved",
  "dataset": {
    "uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
    "id": 1,
    "name": "dataset1"
  },
  "context": "123456789",
  "id": 2,
  "approved": false,
  "denied": false
}

4.5.4. /api/v1/permission_requests/{id} DELETE

Delete a specific permission request by identifier.

Input: Permission request identifier in the URL

Output

{
  "code": 200,
  "status": "Deleted",
  "message": "Permission request successfully deleted"
}

4.5.5. /api/v1/permission_requests/search GET

Search for permission requests by user email, operation, dataset UUID and/or context.

Input: Permission request parameters in JSON body

{
  "user_email": "user1@example.com",
  "operation": "transfer",
  "dataset_uuid": "9ccd087e-f70c-4c4e-b0e7-4a46d67e99e0",
  "context": "123456789"
}

Output

[
  {
    "user_email": "user1@example.com",
    "operation": "transfer",
    "dataset_uuid": "9ccd087e-f70c-4c4e-b0e7-4a46d67e99e0",
    "context": "123456789"
  }
]

4.6. Permission Responses

4.6.1. /api/v1/permission_responses/{id}/{decision} GET

This HTTP call is provided for users to either approve or deny a permission request. The user needs to be logged in to perform this action. If the user is not yet logged in, the login page is shown. No JWT token is needed.

Input: Permission request identifier and decision (‘approve’ or ‘deny’) in the URL.

Output: The user is shown a list of permission requests and previous responses.

4.7. Allowed Operations

4.7.1. /api/v1/allowed_operations/{dataset_uuid}/{user_email} GET

List allowed operations of a specific user for a dataset.

Input: Dataset UUID and user email in the URL

Output

{
  "transfer": "123456789"
}

4.7.2. /api/v1/multiple_allowed_operations/{dataset_uuid}/{user_email} GET

List allowed operations of a specific user for a dataset, and enumerate all possible contexts.

Input: Dataset UUID and user email in the URL

Output

{
  "transfer": ["123456789", "some other context"]
}