Changes between Version 9 and Version 10 of UniformClearinghouseAPI

08/14/13 15:35:26 (6 years ago)



  • UniformClearinghouseAPI

    v9 v10  
     263== API Method Examples (cont.): ==
     265An example of create_slice call would specify required options e.g.:
     269      ‘fields’ : {
     271            “SLICE_NAME”: “TEST_SLICE”,
     273            “SLICE_DESCRIPTION”: “My Test Slice”,
     275            “SLICE_EMAIL”:,
     277            “PROJECT_URN”: “urn:publicid+IDN+this_sa+project+myproject”
     279       }
     283and receive a return dictionary looking like:
     287       “SLICE_URN”: “”,
     289       “SLICE_UID”: “…”,
     291       “SLICE_NAME”: “TESTSLICE”,
     293       “SLICE_CREDENTIAL”: “.....”,
     295       “SLICE_DESCRIPTION”: “My Test Slice”,
     297       “PROJECT_URN”: “urn:publicid+IDN+this_sa+project+myproject”,
     299       “SLICE_EXPIRATION”: “2013-08-29T13:15:30Z”,
     301       “SLICE_EXPIRED”: “FALSE”,
     303       “SLICE_CREATION”: “2013-07-29T13:15:30Z”,
     305       “SLICE_EMAIL”:
     309== API Authentication ==
     311This document suggests that the Authentication required for the CH is implicit in the SSL protocol: the invoker of the call must have its cert and private key to have a valid SSL connection. Moreover, the cert must be signed by a member of the trust chain recognized by the CH.
     313== Support for Speaks-for API Invocations ==
     315Best practices dictate that individuals should speak as themselves: that is, the entity on the other side of an SSL connection is the one referred to by the certificate on the connection. Obviously, people typically use tools or software interfaces to create these connections. When a tool is acting directly on a user’s desktop using the user’s key and cert with the user’s explicit permission, it may be acceptable to consider the tool as speaking as the user. But for many tools, the tool is acting on behalf of the user in invoking CH or AM API calls. In this case, it is important for the tool to not speak as the user but to speak for the user, and to have the service to whom the tool is speaking handle the authorization and accountability of this request accordingly.
     317Accordingly, a Clearinghouse and associated Authorities should support speaks-for API transactions. These API transactions use the same signatures as the calls described in this document, with these enhancements:
     318- The user (spoken-for) URN provided as a ‘speaking-for’ option on the call
     319- The user’s certificate be provided as part of the credentials of the call
     320- The speaks-for credential: a statement signed by the user indicating that the tool has the right to speak for the user, possibly limited to a particular scope (e.g. slice, project, API call, time window).