Newer
Older
"title": "zms-identity northbound API",
"description": "This document describes the OpenZMS Identity service northbound API.",
"version": "1.0.0",
"license": {
"name": "Apache 2.0",
"identifier": "Apache-2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.txt"
}
},
"servers": [
{
"url": "http://localhost:8000/v1"
}
],
"components": {
"schemas": {
"Error": {
"properties": {
"error": {
"example": "The main error message.",
"type": "string"
},
"errors": {
"items": {
"example": "Additional errors, if any.",
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"Version": {
"properties": {
"branch": {
"example": "master",
},
"build_timestamp": {
"example": "2020-12-18T21:06:28.000Z",
"format": "date-time",
},
"commit": {
"example": "deadbeef",
},
"major": {
"example": 0,
"type": "integer"
},
"minor": {
"example": 1,
"type": "integer"
},
"patch": {
"example": 0,
"type": "integer"
},
"version": {
"example": "0.1.0",
"type": "string"
}
},
"required": [
"major","minor","patch","version"
],
"type": "object"
},
"User": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"name": {
"description": "The username.",
"type": "string"
"given_name": {
"type": "string",
"description": "Given name.",
"example": "John"
},
"family_name": {
"type": "string",
"description": "Family name.",
"example": "Doe"
},
"full_name": {
"type": "string",
"description": "Full name.",
"example": "John Doe"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Creation time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"deleted_at": {
"type": "string",
"format": "date-time",
"description": "Deletion time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"enabled": {
"type": "boolean",
"description": "User account status."
},
"password": {
"type": "string",
"nullable": true,
"format": "password",
"description": "The user's password, if any; only changeable, never returned. `password` must be base64-encoded."
"primary_email_address_id": {
"description": "The id of the User's primary email address.",
"type": "string",
"nullable": true,
"format": "uuid",
"x-immutable-on-post": true
},
"primary_email_address": {
"$ref": "#/components/schemas/UserEmailAddress",
"x-ref-nullable": true
},
"email_addresses": {
"type": "array",
"nullable": true,
"description": "List of all email addresses.",
"items": {
"$ref": "#/components/schemas/UserEmailAddress"
}
},
"idp_identities": {
"type": "array",
"$ref": "#/components/schemas/UserIdpIdentity"
},
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"role_bindings": {
"type": "array",
"nullable": true,
"items": {
"$ref": "#/components/schemas/RoleBinding"
},
"x-immutable-on-put": true,
"x-immutable-on-post": true
}
},
"type": "object",
"required": [
"name"
]
"type": "object",
"description": "A list of users.",
"properties": {
"users": {
"items": {
"$ref": "#/components/schemas/User"
},
"type": "array"
},
"page": {
"type": "integer",
"nullable": true,
"description": "The page number of this list."
},
"total": {
"type": "integer",
"nullable": true,
"description": "The total number of items available in this list pagination."
},
"pages": {
"type": "integer",
"nullable": true,
"description": "The total number of pages in this list pagination."
},
"UserEmailAddress": {
"type": "object",
"properties": {
"id": {
"description": "The id of the email address.",
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"user_id": {
"description": "The user_id of the email address.",
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"email_address": {
"type": "string",
"description": "Email address."
}
},
"required": [
"email_address"
]
},
"UserIdpIdentity": {
"type": "object",
"properties": {
"id": {
"description": "The id of the IdP identity.",
"example": "",
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"sub": {
"type": "string",
"description": "OAuth2/OIDC subject unique identifier"
},
"aud": {
"type": "string",
"description": "Token audience (OIDC client_id)"
},
"iss": {
"type": "string",
"description": "Token issuer"
},
"idp": {
"type": "string",
"description": "IdP identifier"
},
"format": "email",
"description": "Email address."
},
"name": {
"type": "string",
"nullable": true,
"description": "IdP user display name"
},
"required": [
"sub",
"iss",
"idp",
"email_address"
]
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
},
"Token": {
"type": "object",
"properties": {
"id": {
"description": "The token id.",
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"user_id": {
"description": "The owning user id.",
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"token": {
"description": "The token value.",
"example": "",
"type": "string",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"expires_at": {
"type": "string",
"description": "The expiration time as an ISO 8601 string, if any.",
"example": "2023-06-30T22:11:05.242530Z",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"issued_at": {
"type": "string",
"format": "date-time",
"description": "The issue time as an ISO 8601 string.",
"example": "2023-06-30T22:10:05.242530Z",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"role_bindings": {
"description": "A list of TokenRoleBindings this token is associated with.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRoleBinding"
},
"x-immutable-on-put": true,
"x-immutable-on-post": true
}
},
"required": [
"user_id",
"token",
"issued_at"
]
},
"TokenList": {
"type": "object",
"properties": {
"tokens": {
"items": {
"$ref": "#/components/schemas/Token"
},
"type": "array"
}
}
},
"TokenRoleBinding": {
"type": "object",
"description": "An object that associates a RoleBinding with a Token to express a Many (RoleBinding) to One (Token) relationship.",
"properties": {
"token_id": {
"description": "The token id.",
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"role_binding_id": {
"description": "The role binding id.",
"type": "string",
"format": "uuid",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"role_binding": {
"description": "The associated role binding.",
"$ref": "#/components/schemas/RoleBinding",
"x-immutable-on-put": true,
"x-immutable-on-post": true
}
},
"required": [
"token_id",
"role_binding_id"
]
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
"Element": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the element.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"creator_user_id": {
"type": "string",
"format": "uuid",
"description": "The originating user id.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"name": {
"type": "string",
"description": "The name of the element.",
"example": "POWDER"
},
"description": {
"description": "A brief description of the element.",
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"approved_at": {
"type": "string",
"format": "date-time",
"nullable": true,
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Last update time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"deleted_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Deletion time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"enabled": {
"type": "boolean",
"description": "Element is enabled to operate in OpenZMS.",
"html_url": {
"type": "string",
"nullable": true,
"description": "A URL associated with this element that is meaningful to the requestor; opaque to OpenZMS."
},
"attributes": {
"description": "A list of attributes associated with the element.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ElementAttribute"
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
},
"ElementAttribute": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the element attribute.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"element_id": {
"type": "string",
"format": "uuid",
"description": "The associated element id.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"kind": {
"type": "string",
"description": "The attribute kind (e.g. link)."
},
"name": {
"type": "string",
"description": "The attribute name."
},
"value": {
"type": "string",
"description": "The attribute value."
},
"description": {
"type": "string",
"description": "A brief description of the attribute (e.g., summary of URL content or purpose)."
}
}
},
"ElementList": {
"properties": {
"elements": {
"items": {
"$ref": "#/components/schemas/Element"
},
"type": "array"
}
},
"type": "object"
},
"Service": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the service.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"name": {
"type": "string",
"description": "The name of the service.",
"x-immutable-on-put": true
},
"kind": {
"type": "string",
"description": "The kind of service.",
"example": "zms",
"x-immutable-on-put": true
},
"endpoint": {
"type": "string",
"format": "uri",
"description": "The service's gRPC endpoint.",
"example": ""
},
"endpoint_api_uri": {
"type": "string",
"format": "uri",
"description": "The services's RESTful API endpoint",
"example": "https://localhost:3000"
},
"description": {
"description": "A brief description of the service.",
"type": "string"
},
"version": {
"description": "The service's version string.",
"type": "string"
},
"api_version": {
"description": "The service's RESTful API version string.",
"type": "string"
},
"enabled": {
"description": "True if the service is enabled for use.",
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"heartbeat_at": {
"type": "string",
"format": "date-time",
"description": "Last heartbeat message time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"ServiceList": {
"properties": {
"services": {
"items": {
"$ref": "#/components/schemas/Service"
},
"type": "array"
}
},
"type": "object"
},
"Role": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the role.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"name": {
"type": "string",
"description": "The name of the role.",
"example": "member",
"x-immutable-on-put": true
},
"value": {
"description": "The integer value of the role; higher implies greater privileges.",
"type": "integer"
},
"description": {
"description": "A brief description of the role intent.",
"example": "This is a role that allows you to create resources.",
"type": "string"
}
},
"required": [
"name"
]
},
"RoleList": {
"properties": {
"roles": {
"items": {
"$ref": "#/components/schemas/Role"
},
"type": "array"
}
},
"type": "object"
},
"RoleBinding": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the rolebinding.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"role_id": {
"type": "string",
"format": "uuid",
"description": "The id of the role."
},
"user_id": {
"type": "string",
"format": "uuid",
"description": "The id of the user."
},
"element_id": {
"type": "string",
"format": "uuid",
"description": "The id of the element this binding is associated with, if any."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation time.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"approved_at": {
"type": "string",
"format": "date-time",
"description": "Approval time, if any.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"deleted_at": {
"type": "string",
"format": "date-time",
"description": "Deletion time, if any.",
"x-immutable-on-put": true,
"x-immutable-on-post": true
},
"role": {
"$ref": "#/components/schemas/Role",
"x-ref-nullable": true
},
"RoleBindingList": {
"properties": {
"role_bindings": {
"items": {
"$ref": "#/components/schemas/RoleBinding"
},
"type": "array"
}
},
"type": "object"
},
"EventHeader": {
"type": "object",
"properties": {
"type": {
"type": "integer",
"description": "The type of event; defined generally in https://gitlab.flux.utah.edu/openzms/zms-api/-/blob/main/docs/zms/event/v1/event.md?ref_type=heads#zms-event-v1-EventType .",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"code": {
"type": "integer",
"description": "The code of event; service-defined.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
"source_type": {
"type": "integer",
"description": "The type of event; defined generally in https://gitlab.flux.utah.edu/openzms/zms-api/-/blob/main/docs/zms/event/v1/event.md?ref_type=heads#zms-event-v1-EventSourceType .",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"source_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the source service.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the event.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"time": {
"type": "string",
"format": "date-time",
"description": "The event timestamp.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"object_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the object on which the event occurred.",
"x-immutable-on-post": true,
"x-immutable-on-put": true,
"nullable": true
},
"user_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the user with with the event object is associated, if any.",
"x-immutable-on-post": true,
"x-immutable-on-put": true,
"nullable": true
},
"element_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the element with with the event object is associated, if any.",
"x-immutable-on-post": true,
"x-immutable-on-put": true,
"nullable": true
},
"Event": {
"type": "object",
"description": "A per-service Event data type that utilizes the generic EventHeader type and associates per-service objects.",
"properties": {
"header": {
"$ref": "#/components/schemas/EventHeader"
},
"object": {
"description": "The object on which the event occurred, if any.",
"x-determinant": {
"propertyPath": "header.code",
"mapping": {
"1001": "#/components/schemas/User",
"1002": "#/components/schemas/Element",
"1003": "#/components/schemas/Role",
"1004": "#/components/schemas/RoleBinding",
"1005": "#/components/schemas/Token",
"1006": "#/components/schemas/Service"
},
"default": {
"$ref": "#/components/schemas/AnyObject"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/User"
},
{
"$ref": "#/components/schemas/Element"
},
{
"$ref": "#/components/schemas/Role"
},
{
"$ref": "#/components/schemas/RoleBinding"
},
{
"$ref": "#/components/schemas/Token"
},
{
"$ref": "#/components/schemas/Service"
},
{
"$ref": "#/components/schemas/AnyObject"
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
},
"EventFilter": {
"type": "object",
"properties": {
"types": {
"type": "array",
"description": "A list of integer event types, one of which must match for the EventFilter to match. If the list is empty, any type is matched.",
"items": {
"type": "integer"
},
"x-immutable-on-put": true
},
"codes": {
"type": "array",
"description": "A list of integer event codes, one of which must match for the EventFilter to match. If the list is empty, any code is matched.",
"items": {
"type": "integer"
},
"x-immutable-on-put": true
},
"object_ids": {
"type": "array",
"description": "A list of event object UUIDs, one of which must match for the EventFilter to match. If the list is empty, any object UUID is matched.",
"items": {
"type": "string",
"format": "uuid"
},
"x-immutable-on-put": true
},
"user_ids": {
"type": "array",
"description": "A list of event object-associated user UUIDs, one of which must match for the EventFilter to match. If the list is empty, any associated user UUID is matched. Typically this will be the owner UUID of the object on which the event occurred.",
"items": {
"type": "string",
"format": "uuid"
},
"x-immutable-on-put": true
},
"element_ids": {
"type": "array",
"description": "A list of event object-associated element UUIDs, one of which must match for the EventFilter to match. If the list is empty, any associated element UUID is matched. Typically this will be the owning element UUID of the object on which the event occurred.",
"items": {
"type": "string",
"format": "uuid"
},
"x-immutable-on-put": true
}
}
},
"AnyObject": {
"type": "object",
"additionalProperties": true
},
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
"Subscription": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the subscription.",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"filters": {
"type": "array",
"description": "A list of event filters that define the subscription.",
"items": {
"$ref": "#/components/schemas/EventFilter"
},
"x-immutable-on-put": true
},
"endpoint": {
"description": "The subscribed endpoint (e.g., `<host>:<port>`).",
"type": "string",
"x-immutable-on-post": true,
"x-immutable-on-put": true
},
"endpoint_type": {
"description": "The subscribed endpoint type.",
"type": "string",
"x-immutable-on-post": true,
"x-immutable-on-put": true
}
},
"required": [
"id"
]
},
"SubscriptionList": {
"properties": {
"subscriptions": {
"items": {
"$ref": "#/components/schemas/Subscription"
},
"type": "array"
}
},
"type": "object"
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
},
"CreateToken": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"password",
"token",
"idp"
]
},
"credential": {
"x-determinant": {
"propertyPath": "method",
"mapping": {
"password": "#/components/schemas/CreateTokenCredentialPassword",
"token": "#/components/schemas/CreateTokenCredentialToken",
"idp": "#/components/schemas/CreateTokenCredentialIdp"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/CreateTokenCredentialPassword"
},
{
"$ref": "#/components/schemas/CreateTokenCredentialToken"
},
{
"$ref": "#/components/schemas/CreateTokenCredentialIdp"
}
]
},
"role_binding_ids": {
"type": "array",
"description": "A list of rolebinding IDs that the new token should include. Must be either owned by the authenticating user in the password and idp method cases; or in the `token` method case, a subset of the rolebinding IDs associated with the token in the request body.",
"items": {
"type": "string",
"format": "uuid"
}
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "The expiration time as an ISO 8601 string, if any.",
"example": "2023-06-30T22:11:05.242530Z"
},
"admin_if_bound": {
"type": "boolean",
"description": "By default, we do not add the admin role to any token unless this field is set `true`. This field will add in an admin role if the user has one, but will not cause an error if the user does not have that role binding. Finally, if this field is set `true`, it will augment the values in the `role_binding_ids`, but if it is `false` or unset, and if the user's `admin` role_binding ID is present in the `role_binding_ids` field, the user's admin role binding will be included in the new token."
},
"token_type": {
"type": "string",
"description": "Set the token type explicitly; may be ignored. This option may be deprecated and removed in the future. For now, API users not building a frontend should not set this option, or should always set `pat`",
"enum": [
"user",
"pat"
],
"default": "pat"
}
},
"required": [
David Johnson
committed
"method"
]
},
"CreateTokenCredentialPassword": {
"type": "object",
"properties": {
"username": {
"type": "string",
"description": "The username or email address."
},
"password": {
"type": "string",
"format": "password",
"description": "The user's password, for direct login. `password` must be base64-encoded."