# Activate a subject for this policy entry derived from the token

`POST /api/2/policies/{policyId}/entries/{label}/actions/activateTokenIntegration`

**This action only works when authenticated with a Json Web Token (JWT).**

Based on the authenticated token (JWT), **this policy entry** is checked to match those conditions:
* the authenticated token is granted the `EXECUTE` permission to perform the `activateTokenIntegration` action
* one of the subject IDs is contained in the authenticated token
* at least one `READ` permission to a `thing:/` resource path is granted

When all conditions match, a new subject is **injected into this policy entry** calculated with information
extracted from the authenticated JWT.

The injected subjects expire when the JWT expires. The `expiry` timestamp (a string in ISO-8601 format)
specifies how long the specific subject will have access to the resource secured by the policy.
The subject will be automatically deleted from the policy once this timestamp is reached.
To give the subject a chance to prolong the access he can configure a connection to get announcements.
Policy announcements are published to websockets and connections that have the relevant subject ID.

The settings under `announcement` control when a policy announcement is published (before expiry or when deleted).
If the field `requestedAcks` is set, then the announcements are published with at-least-once delivery until
the acknowledgement requests under labels are fulfilled.
If a "beforeExpiry" announcement was sent without acknowledgement requests, or the a "beforeExpiry"
announcement was acknowledged, the "whenDeleted" announcement will not be triggered.

Authentication (security requirement alternatives):

```json
[
  {
    "OpenIDConnect": []
  },
  {
    "NginxBasic": []
  },
  {
    "Bearer": []
  }
]
```

- OpenIDConnect: openIdConnect. OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.
- NginxBasic: http (basic). Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
- Bearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Parameters:

- `policyId` (path, string, required) - The ID of the policy needs to follow the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)).

The namespace needs to:
* conform to the reverse domain name notation
  Type: string

- `label` (path, string, required) - The label of a policy entry
  Type: string

Request body: application/json

Optional request payload for `activateTokenIntegration` policy action.

Type: any

- `announcement` (optional)
  Reference: [SubjectAnnouncement](https://sourcey-ditto.pages.dev/http-api-doc/models/subjectannouncement.md); Type: SubjectAnnouncement
  
  Settings for announcements to be made about the subject.
  
  Example:
  
  ```json
  {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "randomizationInterval": "5m"
  }
  ```

```json
{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}
```

Responses:

- 204: The request was successful. The subject was injected.

- 400: The request could not be completed because the authentication was not performed with a JWT.

- 403: The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on this
policy entry.

- 404: The request could not be completed because this policy entry did not match the following conditions:
* containing a a subject ID matching the JWT's authenticated subject
* containing a `READ` permission granted to a `thing:/` resource path

## Examples

### cURL

```bash
curl -X POST 'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/actions/activateTokenIntegration' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}`;

const response = await fetch('https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/actions/activateTokenIntegration', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}'''

response = requests.post(
    'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/actions/activateTokenIntegration',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```