All endpoints require that a valid access_token is provided, and that this token provides the scope necessary to use the given service.
Available services
OpenID Connect
Instead of implementing calls to some of the services below, you can instead implement OIDC to get the info as claims in an OpenID Connect token from the token endpoint instead of having to make a separate call. Read more about our OIDC-implementation here: 🟡OpenID Connect.
User-API V3
This is the new way of accessing user info. If you're making something new, we recomment that you use this service.
NOTE: The contents of this response depends on what scopes the client app is granted, so it will look different depending on what app generated the access_token.
User Info: By uuid endpoint
Some services will need to look up a user based on uuid. For instance to keep user data in sync between different systems. Even after the user has logged out. This endpoint can help in this regard.
This endpoint can be used exactly like the /me-endpoint, only with the uuid instead of me. The result will be the same, so this use case is limited. If you don’t have an access_token, you must provide your client_id as a parameter, and in addition the request must be signed. Your application needs to have the user_consumer role to use this service without an access_token.
WARNING: Requests to this service without access_token requires a signature and user_consumer role.
URI
GET https://www.aid.no/api/mercury/v2/users/:uuid
Required scope
This endpoint requires any of:
Title
Title
Scope
Result
id
id and uuid in response
uuid
uuid in response
name
name in response
email
email in response
phone
phone in response
birth_date
birth_date in response
two_factor_enabled
two_factor_enabled in response
avatar
Link to user’s avatar URL in response (Profile picture)
tracking_key
tracking_key used for tracking statistics about user in response
external_accounts
List of user’s external accounts (Facebook etc.) in response
NOTE: The contents of this response depends on what scopes the client app is granted, so it will look different depending on what app generated the access_token.
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
400
request.parameter.missing
Required parameter missing in request
parameter=%s
403
request.access.role.missing
Application does not have access to required role
This endpoint requires that the application has access to role=%s
403
request.access.signature.invalid
Signature does not match request or secret
Provided signature does not match using the application secret and request URL with parameters (included posted fields)
403
request.access.timestamp.invalid
Timestamp not currently valid
Provided timestamp is not valid, current time on server is: %s
404
user.not_found.by_uuid
User not found
No user found with uuid=%s
User Info: By username endpoint
For use cases where you need to look up a user based only on a username, this is the service for you. But to protect the user’s privacy, this service both requires the user_consumer role and either a pre approved scope for the application or a scope approved by the user before this endpoint is called.
This endpoint can be used sending a signed GET request to the URI. If the username exists, and a scope is approved, it will provide a user response with the attributes allowed by the approved scope, if not an empty 204 response. If the username does not exist, the response will be an empty 404 response.
Since this endpoint does not use an access_token, you must provide your client_id as a parameter, and in addition the request must be signed.
WARNING: Requests to this service requires a signature and user_consumer role.
URI
GET https://www.aid.no/api/mercury/v2/users/find/:username
Required scope
No scope is required to use this service, access is limited by roles. Without scope, no details about the user will be provided.
NOTE: The response will be empty if no scope is provided, but with either response code 204 if the username exists, or 404 if it does not. If scope is provided the response will be a user object if the user exists.
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
400
request.parameter.missing
Required parameter missing in request
parameter=%s
403
request.access.role.missing
Application does not have access to required role
This endpoint requires that the application has access to role=%s
403
request.access.signature.invalid
Signature does not match request or secret
Provided signature does not match using the application secret and request URL with parameters (included posted fields)
403
request.access.timestamp.invalid
Timestamp not currently valid
Provided timestamp is not valid, current time on server is: %s
User Info: Existence by username
In some cases it’s helpful to know if a certain phone or email exists in aID before sending the user to OAuth authorization. For instance if the user has performed a purchase, and in that process has entered a mobile phone number, the application might want to handle the authorization differently based on the existence of that phone number in aID. If the phone number does not exist, the application could use the create_aid custom action, and even pre fill it using custom fields. This is the endpoint to check for the existence of a phone or email (username) in aID.
This endpoint can be used sending a signed GET request to the URI. If the username exists, it will provide an empty 204 response. If the username does not exist, the response will be an empty 404 response.
Since this endpoint does not use an access_token, you must provide your client_id as a parameter, and in addition the request must be signed.
WARNING: Requests to this service requires a signature and user_consumer role.
URI
GET https://www.aid.no/api/mercury/v2/users/exists/:username
Required scope
No scope is required to use this service, access is limited by roles.
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
400
request.parameter.missing
Required parameter missing in request
parameter=%s
403
request.access.role.missing
Application does not have access to required role
This endpoint requires that the application has access to role=%s
403
request.access.signature.invalid
Signature does not match request or secret
Provided signature does not match using the application secret and request URL with parameters (included posted fields)
403
request.access.timestamp.invalid
Timestamp not currently valid
Provided timestamp is not valid, current time on server is: %s
User Info: Report activity
aID needs to store a consent between the user and a legal entity before that legal entity can access the aID user. If the user has no registered activity for a period of time (6 months), the given consent will be revoked. The user will then have to give a new consent for this legal entity before the aID can be used on those sites.
Activity is registered each time a user logs in, or when any aID service is called with a user’s access_token. But we do not want the user to log in several times, and the logged in session is valid for a long period. In order to keep the consent, legal entities need to report activity for their users. This is done by calling this endpoint.
Please do not call this endpoint every time activity for a user is detected on your site. This will result in overload of our systems. Limit the number of calls to this service to once a day per active user. For example the first time you see activity on a user per day.
This endpoint can be used sending GET request to the URI. If the access_token is valid, an activity will be registered with the associated user and a 204 response will be returned. If the access_token is invalid, the response will be an 401 response.
URI
GET https://www.aid.no/api/mercury/v2/users/report_activity
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
User-groups services
These services are used to get information related to user’s groups, like families or company memberships.
aID users are encouraged to create a family group with family members they share a home with (household). This can be done here. The main reason for doing so is to share subscriptions.
There are two types of groups:
.1FAMILY: A user will only be able to join one family but exceptions can be made. In a family, all shareable subscriptions should be shared with all other members of the family. This can be done by adding up all access known for the uuid of each of the members of all the groups of type FAMILY the user is a member of.
.2COMPANY: Companies should be handled differently, since they can contain lots of members. Instead of finding access for all the members, the access should be stored on the uuid of the group instead. So the user will get it’s own access plus access of the uuid’s of all groups of type COMPANY.
The responses for group services will contain uuid of the groups and members of groups, but no personal information about the members, like name, phone etc. To get this information you must use one of the other services described here. Normal privacy restrictions apply, like the user having to give access to your legal entity or OAuth client prior to the service being called. Normally uuid should be sufficient.
An OAuth client can only get and manage company groups owned by the legal entity for that client. The reason for this is that company groups are used to give access to something for a given number of users. This number is seldom the same for access needed to services on all legal entities.
User groups: Me endpoint
This is the service to use when you need to get the groups for a currently logged in user.
URI
GET https://www.aid.no/api/mercury/v2/users/me/groups
Some services will need to look up user groups based on the user’s uuid. This endpoint will do just that.
This endpoint can be used almost exactly like the /me-endpoint, only with the uuid instead of me and you must provide your client_id as a parameter. The result will be the same. In addition the request must be signed. Your application needs to have the user_consumer role.
WARNING: Requests to this service requires a signature and user_consumer role.
URI
GET https://www.aid.no/api/mercury/v2/users/:uuid/groups
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
400
request.parameter.missing
Required parameter missing in request
parameter=%s
403
request.access.role.missing
Application does not have access to required role
This endpoint requires that the application has access to role=%s
403
request.access.signature.invalid
Signature does not match request or secret
Provided signature does not match using the application secret and request URL with parameters (included posted fields)
403
request.access.timestamp.invalid
Timestamp not currently valid
Provided timestamp is not valid, current time on server is: %s
User groups: Create for current user endpoint
This is the service to use when you need to create a new group for a currently logged in user. The user will be set as administrator for the group. No other members will be present before the user invites more members.
The response includes a self_service link. This is the link to the page where the user can administrate the created group by inviting, removing, promoting members and changing the name of the group.
WARNING: Groups of type FAMILY can not be created using this API, they must be created by the user on www.aid.no.
WARNING: Requests to this service requires the group_manager role.
URI
POST https://www.aid.no/api/mercury/v2/users/me/groups
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
400
request.parameter.missing
Required parameter missing in request
parameter=%s
400
request.field.missing
Required field is missing in request
field=%s
400
request.field.invalid
Required field contains invalid value in request
field=%s
403
request.access.role.missing
Application does not have access to required role
This endpoint requires that the application has access to role=%s
400
group.type.not_implemented
Support for provided group type is not implemented in the API.
type=%s, valid types are: “company”
400
group.legal_entity.missing
Group or OAuth application is missing legal entity
Legal entity must be set on OAuth applications using group API and groups administrated through the API
User groups: Update for current user endpoint
This is the service to use when you need to update a group administrated by the currently logged in user.
Only updating name and allotments is supported.
When updating the number of allotments to a smaller number, the update will fail if the new allotments number is smaller than the current number of members in the group.
WARNING: Groups of type FAMILY can not be updated using this API.
WARNING: Requests to this service requires the group_manager role.
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
400
request.parameter.missing
Required parameter missing in request
parameter=%s
400
request.field.missing
Required field is missing in request
field=%s
400
request.field.invalid
Required field contains invalid value in request
field=%s
403
request.access.role.missing
Application does not have access to required role
This endpoint requires that the application has access to role=%s
404
group.not_found.by_uuid
Group not found
No group found with uuid=%s
400
group.legal_entity.missing
Group or OAuth application is missing legal entity
Legal entity must be set on OAuth applications using group API and groups administrated through the API
403
group.legal_entity.not_allowed
Legal entity is not allowed to perform current request on group
The legal entity is not allowed to: %s
403
group.user.not_allowed
User is not allowed to perform current request on group
The user is not allowed to: %s
400
group.allotments.too_low
Allotment set to lower than current number of members.
allotments=%s is lower than members=%d
User-privacy services
These services are used to get information related to user’s privacy preferences etc.
User privacy preferences: Me endpoint
Third parties using aID to log in users are required to respect the users privacy preferences as set by the user on www.aid.no. This is the endpoint to get the current settings for a user.
URI
GET https://www.aid.no/api/mercury/v2/users/me/privacy/preferences
Some services will need to look up user privacy preferences based on uuid. This endpoint can help in this regard.
This endpoint can be used almost exactly like the /me-endpoint, only with the uuid instead of me and you must provide your client_id as a parameter. The result will be the same. In addition the request must be signed. Your application needs to have the user_consumer role.
WARNING: Requests to this service requires a signature and user_consumer role.
Something went wrong internally in the aID system. Error was: %s
503
general.emergency_mode
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
400
request.parameter.missing
Required parameter missing in request
parameter=%s
403
request.access.role.missing
Application does not have access to required role
This endpoint requires that the application has access to role=%s
403
request.access.signature.invalid
Signature does not match request or secret
Provided signature does not match using the application secret and request URL with parameters (included posted fields)
403
request.access.timestamp.invalid
Timestamp not currently valid
Provided timestamp is not valid, current time on server is: %s
Access services
The most common use case for aID is to check for access to content. These services provide ways to do that.
These services introduces the concept of access features, which is only partially implemented in the aID stack, but will probably be more used in the future.
An access feature is something describing what part of the publication the user should have access to.
Some examples:
newspaper - The user has access to anything related to the online edition of the newspaper publication (this is the only implemented access feature now.
amedia_staff - The user is Amedia staff, and will get access to beta features etc.
epaper - The user has access to the epaper edition of the newspaper (not implemented)
pluss - The user has access to pluss articles (not impelemented)
weekendmag - The user has access to the weekend magazine from the publication (in pilot)
Access by Access Features endpoint
If you need to check if a user has access to a certain publication, this is the endpoint to use.
The domain of the publication you wish to check access for (eg. www.glomdalen.no)
access_features
Comma separated list of access features to check for (eg. epaper,pluss)
require
Defaults to all if not present. all means that the user must have all access features to get access. any means that the user needs at least one to get access.
If you need to check which publications a user has access to given a certain access feature, this is the endpoint to use. A use case could be a stand alone application not tightly integrated with a publication, where you want the user to have access if he has access to any publication, or any within a certain list.
aID provides a service for storing key-value pairs in groups called namespaces for a user. A namepace could be anyting, and is used to group collections of key-values. Both keys and values must be strings. They are limited to 50 characters each.
The data model here is by design very simple and not very flexible. It's not a replacement for a RDBMS, so if the application is sufficiently complex, it should have its own storage. But many requirements can be distilled down to a set of key value pairs. By using the aID storage service, the application won't need to handle backup, security, deleting data for removed users (to be GDPR compliant) etc.
Example namespace
An example namespace could be advent_calendar:
{
"opened_door_1":"2024-12-01T13:37"
}
In the above example, "opened_door_1" is a key, and the value for this key is the string representation of a timestamp, when the user opened this door in the calendar. So the next time the user opens the calendar page, the page knows that door number 1 has already been opened.
Note: Thus far, the storage service has only been used by Amedia internal applications, and through Javascript on Amedia sites. So only a tiny part of the API is currently available for third parties using OAuth. Please tell us if you have a need for other services like fetching a namespace for a logged in user, updating a namespace etc.
Getting namespace values for all users
If you have an application like the above "advent_calendar" example, you would have some frontend code allowing users to open doors, and then you would use @amedia/user or some other API to store values to a user's namespace. You can use @amedia/user to get the values back for the currently logged in user, but what if you need to get all values for all users, in order to pick a daily winner or something like that? That is one of the use cases this endpoint tries to solve.
WARNING: Requests to this service requires a signature and storage_consumer role. Client ID must be provided by X-Client-ID HTTP header. Before starting to store data, make sure you associate the data with a valid Client ID, for example by using .withClientStorage() in @amedia/user. If you don't, there's no way to get data for all users.
The response lists UUID's of all users that have saved data in the namespace. For each UUID, you get an object with the key-value pairs stored in the namespace for this user. If you need more information about the user, like the user's email address, you need to call another API using the user's UUID to get this information.
Please don't store copies of data from the aID user here!
Session services
Users are logged in to aid.no using a session. When the user visits Amedia sites, a spinoff session based on this session is created for each site. The ID of the session is stored in a cookie called aid.session in the users browser (on Amedia sites, this will be the ID of the spinoff). When the user logs in to a third party service, and we create an access_token, the token will be associated with the session used during authorization. The following services are available to work with associated sessions.
Getting session from access token
If you are writing a mobile app that needs to perform OAuth login and then set the aid.session cookie in webviews in order to have all webviews in sync with the access token, then this is the service for you!
By setting the value of id in a cookie, the user will be logged in with the same session used to authorize the access_token provided. The cookie should be set as secure, http_only and same_site should be set to lax.
Auto login from access token
If you don't need the session ID, another way to get the user logged in to the same session is using auto login. The advantage is that auto login handles the logic for setting the cookies correctly, getting correct spinoff sessions for publication sites and handles corner cases like what to do if the user is already logged in as another user in the same browser.
URI:
https://www.aid.no/aid/logg_inn/auto
Parameters
Title
Title
Title
Name
Description
access_token
The access token to log in with.
context
The context of the autologging.
Currently implemented values: auto_login_third_party
requestedUrl
The URL the user should be sent to after being logged in.
So by opening a webview using the above URL, with correct parameters, you can get the user logged in on any Amedia site.
If the access token is valid, the user will end up with an aid.session-cookie on www.aid.no, and a spinoff aid.session-cookie on www.sb.no, on the front page of www.sb.no.