Skip to main content
Skip table of contents

Fetching raw statistics data via the API

As well as a mechanism to return aggregated reports, an API call can also be used to retrieve raw data. This gives a flat report in CSV format you can use in analysis tools such as Tableau, Power BI and others.

Additional information includes:

  • date and time of each authentication and transfer

  • The reasons why an authentication failed (e.g. bad password)

  • Whether or not a transfer to a resource was blocked by restrictive mode

Prerequisites

  • The optional reports API functionality to be enabled for your organisation - your account manager will be happy to discuss pricing with you

  • You will need to know your domain’s API name. This is usually, but not always, the same as your federation scope.

  • An API key from each organisation and sub-organisation you will be querying

    • The key will need either the reports API permission (recommended) or the full access permission.

Request

Begin with a GET request to the following URL: https://reports.openathens.net/api/v1/example.org/rawreport?date=<date>

Where example.org is your OpenAthens API name and date is the requested date (format yyyy-MM-dd between yesterday and 30 days ago)

CODE
GET https://reports.openathens.net/api/v1/example.org/rawreport?date=2023-05-22 
Authorization: OAApiKey <api-key>

(There’s an example available using Postman)

Response payload

The response will be an application/vnd.eduserv.iam.reports.task-v1+json object.

If the job completes in under 5 seconds, it will have a status of FINISHED and a href to the report - see downloading below.

If the job is still running after 5 seconds, it will return a status of RUNNING and a href back to the task status.

Your application will need to allow for both types of response. 20s is a reasonable wait time to code if you get a running response.

Example - still running

CODE
GET https://reports.openathens.net/api/v1/example.org/rawreport?date=2023-05-22 
Authorization: OAApiKey <api-key>

Response: HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json
  {
    "percentComplete": 40, 
    "status": "RUNNING", 
    "links": [ 
      { 
        "href": "https://reports.openathens.net/api/v1/example.org/rawtask/a11b5fff-6170-38e3-b4bb-560bee3e6985",
        "rel": "SELF",
        "type": "application/vnd.eduserv.iam.reports.task-v1+json",
        "method": "get" 
      } 
    ], 
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985" 
  }

Example - finished

CODE
GET https://reports.openathens.net/api/v1/example.org/rawtask/a11b5fff-6170-38e3-b4bb-560bee3e6985 
Authorization: OAApiKey <api-key> 
  
Response: HTTP/1/1 200 OK 
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json
  {
    "percentComplete": 100,
    "status": "FINISHED",
    "links": [
     {
       "href": "https://reports.openathens.net/api/v1/example.org/rawreport/a11b5fff-6170-38e3-b4bb-560bee3e6985",
       "rel": "DOWN",
       "type": "application/vnd.eduserv.iam.reports.report-v1+json",
       "method": "get"
      }
    ],
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
  }

Downloading the linked report

Depending on your method you may optionally add a filename parameter to the download URL, e.g. https://reports.openathens.net/api/v1/example.org/rawreport/a11b5fff-6170-38e3-b4bb-560bee3e6985?filename=rawstats_2023-06-20.csv.

Report format

The reports can be very large, so they’re downloaded as a zipped CSV file (MIME types application/gzip and text/csv). Not all fields will have data for all actions:

Heading

Comment

date

UTC Timestamp

e.g. 06/06/2023T19:29:16

action

What happened (see next table)

status

The status of the action

e.g. SUCCESS, ACCOUNT_ERROR_BAD_PASSWORD, FAILURE_RESTRICTIVE

account.authsystemname

Local connector name

e.g. Student login

account.authsystemid

Local connector ID

e.g. 5859e555-ecf1-5afb-ba05-852355423ea6

account.permissionsets

Permission set names connected to the user

e.g. demo#default, demo#extra

account.organisation

The parent organisation of the account

e.g. 123456

account.accountid

The ID of the account

e.g. 07e70182-e565-4be8-b6b1-f2765f13164c

account.type

e.g. LOCAL, PERSONAL

account.status

The status of the account

e.g. PENDING, INVALID, ACTIVE

account.expiry

Account expiry date: only for OpenAthens accounts

e.g. 2024-12-06

location.isp

The user's ISP (where identifiable)

e.g. virginm.net, Btcentralplus

request.countrycode

The ISO country code of the user's location

e.g. GB, US

request.useragent

The user agent string from the user’s browser

e.g. Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:108.0) Gecko/20100101 Firefox/108.0

request.ipaddress

The IP address the user was at

e.g. 13.248.204.98

attribute.resourceid

Only for transfer actions - the entityID of the resource

e.g. https://sp.coolresource.co/entity

attribute.federationctx

Only for transfer actions - a federation identifier

e.g. oafed, ukfed

Custom SAML resources appear as your own OpenAthens API name

attribute.resourcetitle

Only for transfer actions - the resource title (at the time)

e.g. Cool Stuff Inc.

Plus all fields marked as reportable in your Schema editor. These will appear as

attribute.attributename

Actions

Action

Comment

AUTHENTICATE

An OpenAthens account has authenticated

LOCAL_AUTHENTICATE

A local account has authenticated

FEDERATED_TRANSFER

An OpenAthens accounts has been sent to a resource

LOCAL_FEDERATED_TRANSFER

A local account has been sent to a resource

How often should I run the reports?

Reports only cover one day at a time, and only go back 30 days. If scheduling them we would suggest a daily or weekly cycle. This will give you time to spot any days that don’t run for any reason and address them.

Anything to watch out for?

Changes to the reportable state of attributes in your schema will only affect items recorded after the change is saved.

The report will only cover the organisation where the API key sits, so if you have sub-organisations you will need an API key from each and will need to make additional requests with those keys.

All times and dates are UTC so your timezone can affect when yesterday’s data becomes available.

(There’s an example available using Postman)

Location data

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com  

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.