You are browsing the docs for Nexus v1.5.x, the latest release is available here
Realms
Realms are rooted in /v1/realms
collection.
Each realm defines a specific authentication provider. Any of the authentication providers can be used to obtain access tokens that can be used with Nexus.
When modifying realms, the caller must have realms/write
permissions on the path /
.
When reading realms, the caller must have realms/read
permissions on the path /
.
Please visit Authentication & authorization section to learn more about it.
Create
This operation creates a realm.
PUT /v1/realms/{realm}
The following examples describe the payload used to create a realm.
Example
- Request
-
source
curl -XPUT \ -H "Content-Type: application/json" \ "http://localhost:8080/v1/realms/realm1" \ -d '{ "name":"Nexus Dev", "openIdConfig":"http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration", "logo":"http://localhost:8080/logo.png" }'
- Payload
-
source
{ "name": "Nexus Dev", "openIdConfig": "http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration", "logo": "http://localhost:8080/logo.png" }
- Response
-
source
{ "@context": [ "https://bluebrain.github.io/nexus/contexts/realms-metadata.json", "https://bluebrain.github.io/nexus/contexts/metadata.json" ], "@id": "http://localhost:8080/v1/realms/realm1", "@type": "Realm", "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json", "_createdAt": "2021-05-11T09:42:41.313Z", "_createdBy": "http://localhost:8080/v1/anonymous", "_deprecated": false, "_label": "realm1", "_rev": 1, "_self": "http://localhost:8080/v1/realms/realm1", "_updatedAt": "2021-05-11T09:42:41.313Z", "_updatedBy": "http://localhost:8080/v1/anonymous" }
The logo
parameter is optional.
Update
This operation updates a realm.
PUT /v1/realms/{realm}?rev={previous_rev}
{...}
where {previous_rev}
is the last known revision number for the realm. The json payload should be the same as the one used to create realms.
Example
- Request
-
source
curl -XPUT \ -H "Content-Type: application/json" \ "http://localhost:8080/v1/realms/realm1?rev=1" \ -d '{ "name":"Nexus Dev", "openIdConfig":"http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration", "logo":"http://localhost:8080/logo.png" }'
- Payload
-
source
{ "name": "Nexus Dev", "openIdConfig": "http://localhost:8080/auth/realms/bbp-test/.well-known/openid-configuration", "logo": "http://localhost:8080/logo.png" }
- Response
-
source
{ "@context": [ "https://bluebrain.github.io/nexus/contexts/realms-metadata.json", "https://bluebrain.github.io/nexus/contexts/metadata.json" ], "@id": "http://localhost:8080/v1/realms/realm1", "@type": "Realm", "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json", "_createdAt": "2021-05-11T09:42:41.313Z", "_createdBy": "http://localhost:8080/v1/anonymous", "_deprecated": false, "_label": "realm1", "_rev": 2, "_self": "http://localhost:8080/v1/realms/realm1", "_updatedAt": "2021-05-11T09:45:20.409Z", "_updatedBy": "http://localhost:8080/v1/anonymous" }
Deprecate
This operation deprecates a realm.
DELETE /v1/realms/{realm}?rev={previous_rev}
where {previous_rev}
is the last known revision number for the realm.
- Request
-
source
curl -XDELETE "http://localhost:8080/v1/realms/realm1?rev=2"
- Response
-
source
{ "@context": [ "https://bluebrain.github.io/nexus/contexts/realms-metadata.json", "https://bluebrain.github.io/nexus/contexts/metadata.json" ], "@id": "http://localhost:8080/v1/realms/realm1", "@type": "Realm", "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json", "_createdAt": "2021-05-11T09:42:41.313Z", "_createdBy": "http://localhost:8080/v1/anonymous", "_deprecated": true, "_label": "realm1", "_rev": 3, "_self": "http://localhost:8080/v1/realms/realm1", "_updatedAt": "2021-05-11T09:48:57.296Z", "_updatedBy": "http://localhost:8080/v1/anonymous" }
List
Lists all available realms.
GET /v1/realms?from={from}
&size={size}
&deprecated={deprecated}
&rev={rev}
&createdBy={createdBy}
&updatedBy={updatedBy}
&sort={sort}
where…
{from}
: Number - the offset from which to start the listings. Defaults to0
{size}
: Number - the maximum amount fo results to be returned. Defaults to30
{deprecated}
: Boolean - filter the resulting realms based on their deprecation status. Optional parameter.{rev}
: Number - filter the resulting realms based on their revision value. Optional parameter.{createdBy}
: Iri - filter the resulting realms based on their creator. Optional parameter.{updatedBy}
: Iri - filter the resulting realms based on the person which performed the last update. Optional parameter.{sort}
: String - orders the resulting realms based on its metadata fields. Optional parameter that can appear multiple times, further specifying the ordering criteria. Defaults to_createdAt
, ordering realms by creation date.
- Request
-
source
curl "http://localhost:8080/v1/realms"
- Response
-
source
{ "@context": [ "https://bluebrain.github.io/nexus/contexts/metadata.json", "https://bluebrain.github.io/nexus/contexts/search.json", "https://bluebrain.github.io/nexus/contexts/realms.json" ], "_total": 1, "_results": [ { "@id": "http://localhost:8080/v1/realms/realm1", "@type": "Realm", "logo": "http://localhost:8080/logo.png", "name": "BlueBrain", "openIdConfig": "http://localhost:8080/auth/realms/realm1/.well-known/openid-configuration", "_authorizationEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/auth", "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json", "_createdAt": "2021-05-11T09:42:41.313Z", "_createdBy": "http://localhost:8080/v1/anonymous", "_deprecated": true, "_endSessionEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/logout", "_grantTypes": [ "password", "clientCredentials", "refreshToken", "authorizationCode", "implicit" ], "_issuer": "http://localhost:8080/auth/realms/realm1", "_label": "realm1", "_rev": 3, "_self": "http://localhost:8080/v1/realms/realm1", "_tokenEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/token", "_updatedAt": "2021-05-11T09:48:57.296Z", "_updatedBy": "http://localhost:8080/v1/anonymous", "_userInfoEndpoint": "http://localhost:8080/auth/realms/realm1/protocol/openid-connect/userinfo" } ] }
Fetch (current version)
GET /v1/realms/{realm}
Example
- Request
-
source
curl "http://localhost:8080/v1/realms/realm1"
- Response
-
source
{ "@context": [ "https://bluebrain.github.io/nexus/contexts/realms.json", "https://bluebrain.github.io/nexus/contexts/metadata.json" ], "@id": "http://localhost:8080/v1/realms/realm1", "@type": "Realm", "logo": "http://localhost:8080/logo.png", "name": "BlueBrain", "openIdConfig": "http://localhost:8080/auth/realms/BBP/.well-known/openid-configuration", "_authorizationEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/auth", "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json", "_createdAt": "2021-05-11T09:42:41.313Z", "_createdBy": "http://localhost:8080/v1/anonymous", "_deprecated": true, "_endSessionEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/logout", "_grantTypes": [ "password", "clientCredentials", "refreshToken", "authorizationCode", "implicit" ], "_issuer": "http://localhost:8080/auth/realms/BBP", "_label": "realm1", "_rev": 3, "_self": "http://localhost:8080/v1/realms/realm1", "_tokenEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/token", "_updatedAt": "2021-05-11T09:48:57.296Z", "_updatedBy": "http://localhost:8080/v1/anonymous", "_userInfoEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/userinfo" }
Fetch (specific version)
GET /v1/realms/{realm}?rev={rev}
… where {rev}
is the revision number of the resolver to be retrieved.
Example
- Request
-
source
curl "http://localhost:8080/v1/realms/realm1?rev=1"
- Response
-
source
{ "@context": [ "https://bluebrain.github.io/nexus/contexts/realms.json", "https://bluebrain.github.io/nexus/contexts/metadata.json" ], "@id": "http://localhost:8080/v1/realms/realm1", "@type": "Realm", "logo": "http://localhost:8080/logo.png", "name": "BlueBrain", "openIdConfig": "http://localhost:8080/auth/realms/BBP/.well-known/openid-configuration", "_authorizationEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/auth", "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/realms.json", "_createdAt": "2021-05-11T09:42:41.313Z", "_createdBy": "http://localhost:8080/v1/anonymous", "_deprecated": true, "_endSessionEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/logout", "_grantTypes": [ "password", "clientCredentials", "refreshToken", "authorizationCode", "implicit" ], "_issuer": "http://localhost:8080/auth/realms/BBP", "_label": "realm1", "_rev": 3, "_self": "http://localhost:8080/v1/realms/realm1", "_tokenEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/token", "_updatedAt": "2021-05-11T09:48:57.296Z", "_updatedBy": "http://localhost:8080/v1/anonymous", "_userInfoEndpoint": "http://localhost:8080/auth/realms/BBP/protocol/openid-connect/userinfo" }
Server Sent Events
This endpoint allows clients to receive automatic updates from the realms in a streaming fashion.
GET /v1/realms/events
where Last-Event-Id
is an optional HTTP Header that identifies the last consumed realm event. It can be used for cases when a client does not want to retrieve the whole event stream, but to start after a specific event.
The response contains a series of realm events, represented in the following way
data:{payload}
event:{type}
id:{id}
where…
{payload}
: Json - is the actual payload of the current realm{type}
: String - is a type identifier for the current realm. Possible types are: RealmCreated, RealmUpdated and RealmDeprecated{id}
: String - is the identifier of the realm event. It can be used in theLast-Event-Id
HTTP Header
Example
- Request
-
source
curl "http://localhost:8080/v1/realms/events"
- Response
-
source
data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/realms.json"],"@type":"RealmCreated","name":"BlueBrain","openIdConfig":"http://localhost:8080/auth/realms/realm1/.well-known/openid-configuration","_authorizationEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/auth","_endSessionEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/logout","_grantTypes":["password","clientCredentials","refreshToken","authorizationCode","implicit"],"_instant":"2021-05-11T09:42:41.313Z","_issuer":"http://localhost:8080/auth/realms/realm1","_label":"realm1","_realmId":"http://localhost:8080/v1/realms/realm1","_rev":1,"_subject":"http://localhost:8080/v1/anonymous","_tokenEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/token","_userInfoEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/userinfo"} event:RealmCreated id:3abfce50-b23d-11eb-bef4-251deaef3e83 data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/realms.json"],"@type":"RealmUpdated","logo":"http://google.com","name":"BlueBrain","openIdConfig":"http://localhost:8080/auth/realms/realm1/.well-known/openid-configuration","_authorizationEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/auth","_endSessionEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/logout","_grantTypes":["password","clientCredentials","refreshToken","authorizationCode","implicit"],"_instant":"2021-05-11T09:45:20.409Z","_issuer":"http://localhost:8080/auth/realms/realm1","_label":"realm1","_realmId":"http://localhost:8080/v1/realms/realm1","_rev":2,"_subject":"http://localhost:8080/v1/anonymous","_tokenEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/token","_userInfoEndpoint":"http://localhost:8080/auth/realms/realm1/protocol/openid-connect/userinfo"} event:RealmUpdated id:999107a0-b23d-11eb-bef4-251deaef3e83 data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/realms.json"],"@type":"RealmDeprecated","_instant":"2021-05-11T09:48:57.296Z","_label":"realm1","_realmId":"http://localhost:8080/v1/realms/realm1","_rev":3,"_subject":"http://localhost:8080/v1/anonymous"} event:RealmDeprecated id:1ad75c10-b23e-11eb-bef4-251deaef3e83