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"
    },
    "reason": "Reason given by user to request permission",
    "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,
    "decision_tokens": [
      3
    ],
    "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",
  "reason": "Reason given by user to request permission",
  "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"
  },
  "reason": "Reason given by user to request permission",
  "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,
  "decision_tokens": [
    3
  ],
  "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.6. Decision Tokens

4.6.1. /api/v1/decision_tokens/by_permission_request_id/{permission_request_id} GET

List decision tokens for a specific permission request.

Input: Permission request identifier in the URL

Output

{
  "approve_token": "approve_N6Soe_xxAPtPAS5ajkJWoVwtRjQ3CTLw52LA_qrrMyM",
  "deny_token": "deny_dahZbHYPjcMvDydRnHopEUJ1pByJhrRdwb1D7jjK_wU",
  "id": 2
}

4.7. Permission Responses

4.7.1. /api/v1/permission_responses/{id}/{token} 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 token in the URL. The decision token is of the form approve_<long secret> or deny_<long secret> to make debugging easier.

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

4.8. Allowed Operations

4.8.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.8.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"]
}