Create Audit Log Event

POST https://ed.link/api/v2/audit/events

Record a new Event. Events are retained for 30 days, during which they can be viewed and searched. Upon receiving an Event, Edlink will enrich and analyze the event in the context of other recent Events from your platform in order to give you a better picture of what's happening in your system, and to automatically raise warnings around suspicious activity.

If you have defined a Schema for the Event's action, the Event is validated against it. A Schema with validation_level of strict will reject non-conforming Events; a lax Schema (the default) will accept them but flag them. If no Schema exists for the action, the Event is accepted as-is.

You must provide your application secret key in order to access this endpoint. This authentication mechanism is a little bit different than most other requests in our API because it is not made in the "scope" of one particular integration or person. You can find your application secret on the Edlink dashboard.

Request Body

The request body should contain an Event object. actor, action, targets, and scope are required. The context is strongly suggested. The data property is arbitrary and optional.

{
    "action": "assignment.submit",
    "actor": {
        "identifiers": [
            { "value": "00000000-0000-0000-0000-000000000000", "issuer": "edlink" }
        ],
        "type": "person"
    },
    "targets": [
        { "identifiers": [{ "value": "123", "issuer": "acme" }], "type": "assignment" },
        { "identifiers": [{ "value": "ABC", "issuer": "acme" }], "type": "class" }
    ],
    "scope": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "integration"
    },
    "context": {
        "user_agent": "Ladybird",
        "http_method": "POST",
        "http_status": "201",
        "path": "/our/custom/submit/function/path",
        "ip": "1.1.1.1",
        "query": "?title=Test"
    },
    "data": {
        "assignment_title": "Test",
        "student_work_url": "https://example.com/work",
    }
}

Sample Request

axios.post('https://ed.link/api/v2/audit/events', {
    headers: {
        authorization: `Bearer ${application_secret_key}`
    },
    data: {
        actor: {
            identifiers: [
                { value: '00000000-0000-0000-0000-000000000000', issuer: 'edlink' },
                { value: 'acme_user_42', issuer: 'acme' }
            ],
            type: 'person'
        },
        action: 'assignment.submit',
        targets: [
            { identifiers: [{ value: '123', issuer: 'acme' }], type: 'assignment' },
            { identifiers: [{ value: 'ABC', issuer: 'acme' }], type: 'class' }
        ],
        scope: {
            id: '00000000-0000-0000-0000-000000000000',
            type: 'integration'
        },
        context: {
            user_agent: 'Chrome/123'
        }
    }
});

Sample Response

The response will have status 201 Created. The response contains the newly recorded Event id Edlink assigned to it. If there are any validation errors that are still "acceptable" (like in the "context" field parsing, or in a lax Schema), they will appear in the $warnings array.

{
    "$request": "00000000-0000-0000-0000-000000000000",
    "$data": {
        "id": "00000000-0000-0000-0000-000000000000",
    },
    "$warnings": [
        {
            "code": "INVALID_DATA",
            "message": "This is a human-readable description of the warning."
        }
    ]
}

If the Schema is strict, the endpoint will return status 400 Bad Request with the payload containing the $errors details:

{
    "$request": "00000000-0000-0000-0000-000000000000",
    "$errors": [
        {
            "code": "INVALID_DATA",
            "message": "This is a human-readable description of the warning."
        }
    ]
}