Draft: draft-ietf-gnap-core-protocol

Commentary: This changes all instances of " RC " and " resource client " to "  " , short for " client instance " , to allow the protocol to be more precise about where it 's talking about a specific instance of a piece of client software or the client software as a general class which could have many instances . This change seeks to capture some of the concepts from the design team 's work that introduced the concept of a client instance more explicitly . Addresses terminology changes , 
 I disagree . I expect to multi - home the client , so the term client instance would be incorrect . It wo n't even be the same software and the client will be distributed ( micro services ) so the concept of instance is n't even definable . In particular i am distributing the signing so that it is NOT in the web deployed service for security reasons . Also , i was just getting used to recourse client . I liked it . VOTE NO ! 
 Only slightly related point . The idea of instance for a device hosted service of any sort is HIGHLY VALUABLE . I would like to see an instance identifier for anything run on , for example , a user 's smartphone . Is it possible to tease these two concepts apart ? In general we should expect that there will be more than one role , and perhaps more than one piece of software on a smartphone engaged in a single transaction . So that the user agent ( browser ) could very well be completely distinct from a user wallet that would hold , for example , DIDs and their keys . ( Which can not be supported in today 's browsers . ) IMHO , it is the instance that accepts user consent and signs user messages that most clearly needs an instance identifier . 
 It is called client instance because it represents a specific occurrence of a client software ( like a specific version or a specific build target ) , but this has currently nothing to do with the deployment model . 
 what part of the client does the instance refer to ? part that handles the HTTPS . part that handles the UX ( HTML ) . part that signs the jws ? In heavy - use , secure implementations these are all separate software modules , probably running on different systems , on difference o / s and different compilers . Again , for any large installation there is not a single instance to report an identifier . There are cases were a single instance is identifiable as the " source " of the API . If that is what is meant , then that needs to be clarified . But note that is NOT the organization that is running the instance of the API . This issue is very important in , as an example , US Health care where the programer of the API must attest to the code and that is most often not the org that is running the code . Both of these must be accessible in some manner . Somehow we must get from the ID on the " instance " to the legal organization that takes responsibility . As is the case in privacy statements and consent receipts . As was mentioned many months ago , we need a grant request that can be passed from the client through a chain of intermediates to the resource owner to get access to the data . While the chain does not need to be inscope of GNAP , the validation of the grant request after passing thru a chain should be . The provenance of the user and the resource client must be testable at the end of the chain , the Resource Server . That could very well include the guy that wrote the code and the guy that is asking for the data . 
 Really Client Instance ( CI ) is just a sort of generalized  ( in OAuth2 ) , only better suited to advanced needs regarding dynamic device posture handling ( but we 're not discussing attestation for the API here ) , and with the requirement of proving its key possession . The  therefore refers to any communication with the server ( initial request and continuation ) , and that currently involves the different parts that you 're describing ( HTTPS , signature , etc . ) , but there 's currently no way to separate those . I certainly understand the need for modularity on the server side , I 'm not so sure why you 'd need to split the client side also . But this gives me the feeling that we 'd need to really understand your use case to be able to answer correctly ( and this seems to go beyond the current PR ) . 
 I also think renaming the RC is strange . An RC is a client instance just like an AS is an authz server instance and similarly the RC is a particular instance with a certain software installed and a certain identity . The fact that we are talking about a specific instance is better explained once , in the terminology section . 
 I agree with Yaron 's comments that having " instance " in the name is redundant . I suggest we call it the client throughout the specification , and define it as an specific instance of the client in the terminology . We need to differentiate between the two server roles by an adjective ( AS and RS ) -- but there is only one client -- and it is the term used in OAuth and OIDC . Also , RC indicates that the client is only accessing resources -- but in GNAP the client may be requesting claims . ᐧ 
 A big part of what we 're trying to address with this terminology change is that " client " and even " resource client " are too generic of a term here . In OAuth 2 , " client " can mean a specific instance , or the software running an instance , or even just a conceptual entity registered at the AS that 's running a suite of different software . OAuth 2 struggles with this by having " confidential client " and " public client " to talk about different security aspects , and OAuth 2.1 is further trying to fix this mess by introducing " credentialed client " into the mix . The change to " client instance " here is to explicitly call out all of the places in the protocol where we mean exactly -- and only -- a single instance of client software differentiated by its key material . By not re - using the term " client " on its own from OAuth 2 we can avoid taking the luggage and false assumptions about it with us . 
 I do n't think there is as much confusion about what a client is as as you portray . In OAuth , the different adjectives about a client indicate the capabilities of the client . All the rest of the protocol is the same -- in OAuth 2.1 , when client is used , it is all kinds of clients . I agree that we want to define the client as a specific instance of a client -- which is what is doing things in the protocol . Are there places in the draft where we are referring to something other than an instance of a client where we could not use an adjective to clarify ? 
 This pull request is explicit in calling out both " client instance " where an instance is meant and using other modifiers such as " client software " when something else is meant . What is the downside of being explicit about " client instance " throughout the document ? 
 Per comment -- we are not calling out an instance of the AS or an instance of the RS -- so we are being inconsistent between the different software -- and just calling it client has it be consistent with OAuth and OIDC -- otherwise CI makes a reader wonder how it is different -- which it is not . 
 The situation is not symmetrical here ( compared to AS and RS ) , the client is the one that asks for authorization , so it makes sense to gather specific information on that instance . It 's like when someone in your household is asking for a loan to a bank , we do n't really care which branch tells you yes or no , but the bank might care who is asking specifically . 
 it is symmetric . The same AS or RS software can be deployed at different URLs . Which instance of the AS or  is what the client wants to know , just as the AS wants to know which instance of a client . 
 And beyond that I remember we agreed " client " was n't that good a name ( on the mailing list ) . 
 I do n't think there was consensus on that -- or more importantly , that people took the time to participate in that discussion . 
 if it was symmetrical you would n't call them clients and servers , they would just be peers . Most often a client does n't care which instance of a distributed server is running , as long as it can prove it is part of the server . A client instance on the contrary usually comes with individual characteristics of a more generic client software , because it is a specific version running on a specific device ( as an example ) . Anyway it seems that the word " instance " gives rise to various interpretations , way beyond what was defined in the proposed text . 
 I was not saying that the client and server were the same , nor was I giving an example of a distributed server . If two different organizations can run the AS same software from the same vendor , each organization will have its own instance of the same AS software . 
 yes . But that 's a totally different issue . In practice the AS you 're describing is often a multi - tenant architecture ( physically or logically ) but no one cares about posture or attestation ( usually the tenant is hidden from the client , sometimes to the exception of qualitative assessments about the type of environment staging / prod , or the localisation of the tenant ) . There 's really nothing in the protocol that we need to specify for that , it 's standard IT ( containers , reverse proxies etc . exist for that purpose , and industrialized instance management from the same vendor ) . The " client instance " we 're talking about here is fully independant of those RS / AS architectural / deployment choices ( the client does n't need to know ) . But the AS / RS might need to know specific information about the client instance that is making the request . Said differently , the server instance is an implementation detail ( as long as it speaks the protocol and can prove who it claims to be as a server ) , while the client instance is a protocol information in itself . 
 I was not describing a multi - tenant service -- I was describing 2 organizations independently running the same software on their own machines ( or a cloud infrastructure ) . Each AS instance has a unique URL that is the starting endpoint . In the protocol , a client instance is communicating with an AS instance -- which in practice we call the client and the AS . There is also client software and AS software -- which are different concepts than the client instance and the AS instance . My point ( and I believe point ) was why do we need to call it a client instance , but not an AS instance . 
 Deploying your own server does n't change what I explained . I made my best to explain the difference I see in the 2 situations . 
 Which 2 situations are you referring to ? Your last explanation had nothing to do with the point I was trying to make . Note there is instance specific information for each AS -- it 's URL , all the information returned in a discovery call , etc . 
 it has everything to do with it . What I explained as clearly as I can is that there are 2 distinct non symmetrical situations ( client instance vs AS ) . I get that you do n't agree with me , no problem with that . We should try to see what other people in the group think . 
 I do n't actually know what points you are trying to make -- do I do n't think I 'm disagreeing with you . This issue is about the term we use for the client . My position is that adding " instance " to client is odd as we are not adding " instance " to AS or RS 
 Yes . My position is that adding " instance " ( or a similar term if people think instance is odd , but have n't really found a better name ; maybe " handle " is more neutral ? ) to client makes sense and clarifies the protocol ( following the new concept that extends what  does for Oauth2 , and provides static or dynamic device specific information useful to the AS ) , while I see no valid reason to refer to a server " instance " ( which would look much more like a deployment issue ) . I also think we need more feedback on that , maybe as part of the terminology ( but we 'll need to make sure the debate does n't last for weeks and that we can move forward ) . 
 I agree the term  has become problematic in OAuth 2 . With the addition of dynamic client registration , a preregistered clientID represented something very different from a dynamically registered  . I think having a client class identifier and a client instance identifier resolves those issues . When describing the protocol , such as what the client sends the AS , and what the AS does -- it is always an instance of both the client and the AS that we are referring to . Looking over the last commit that Justin made changing CI to client instance , it is unclear how adding " client instance " is better text than " client " 
 The latest commit removes the defined term " client instance " in favor of being explicit throughout the protocol text where we 're talking about a specific instance of the client software vs. the client software itself . Is there a reason we should not be this explicit in the protocol definition ? 
 The reason for not using " client " is that " client " already has a confused meaning in the OAuth 2 world and we are trying to avoid that same confusion here . Having taught hundreds of developers over the years , I can attest that the term and its use are confusing to people , and continue to be in the OAuth 2 world . There is n't a parallel between the AS / RS and client instance . An AS does n't have an instance in the same way that a client does . Within one ecosystem , there 's going to be an AS , regardless of which software it 's running , but many clients . Depending on the type of client software , one bit of software might have many different independent instances . Those might be treated similarly , with the " class identifier " concept , but from the protocol 's perspective they are all independent . This is why it 's important to specify a client instance , but such specificity is n't needed with the AS . 
 I do n't agree that " client " has a confused meaning in OAuth 2 as far as the protocol is concerned - in both OAuth 2 and OIDC , the term is well known . Even if there are many clients in an ecosystem , they all use the protocol the same way . From a client 's perspective , there may be one client , and multiple ASes -- each with the same software , but different instances that have different characteristics . When reading the OAuth 2 or OIDC specs , changing " client " to " client instance " would not improve the understanding . I do n't see how it helps here , and it is confusing on why we are talking about the client instance , but not the AS instance . 
 FWIW : I think we have thrashed around this topic enough between the 3 of us . Time to get some other input in my opinion . 
 The way I see it , whether something is a copy of a particular piece of software is n't the point , it 's about entities acting within the system as a whole . From the perspective of the protocol , there is one AS , and it does n't matter whether that 's running the same software as another AS that 's deployed separately , just as it does n't matter if that AS is actually made up of a bunch of smaller microservices . That 's acting in the role of the AS . There is only one AS instance in the spec . On the other hand , there are always multiple instances of a client within the system . I agree that actually defining the term " Client Instance " is awkward , which is why I 'm happy to see the actual definition changed to just " Client " now . However , using the term " instance " within the prose of the spec helps make it explicit that each instance of the client will have its own keys to use with the AS and RS . As for OAuth , the suggestion was not to change every occurrence of " client " into " client instance " , but there are certainly some cases where it would be clearer to say " client instance " there too , although that 's a discussion for a different group . 
 Justin has confused client instance with the code that has the key . In multihomed clients all of the instances have the ability to get a signature . There are server instances that come and go as the load comes and goes . The server does not prove anything about itself , only about the ability to get a signature . This discussion is emblematic of the core issue --what exactly is it that signed the message . Consider health care . The physician is a user , the client is ( most often ) an Electronic Health Record ( EHR ) server that the physician has access to . The physician issues an order to the EHR on behalf of the patient ( the RO ) . The Client ID is of the EHR . The server can get the request signed by the EHR 's key . The client instance is utterly irrelevant to the entire process . The server is picked from the active server pool . 
 you 're thinking too literally about the term " instance " . It 's not supposed to mean the instance in the ops sense , it 's means exactly what you said in the first sentence , the code that has the key . That 's all that matters from the perspective of the protocol . Given that your summary of what " client instance " means is the intent of the term , I 'd say this text does a good job of describing it . 
 Then i hope that is clear in the doc . Yes - i use english words literally . I would hope that others could do that . I saves a whole lot of explaining outside of the doc to every person on the planet that was not here when this happened . 
 Sorry , I should have said " narrowly " instead of " literally " . The current text says : That feels like it pretty accurately captures the intent of the use of " instance " in the spec . Please feel free to suggest alternative text for the definition if you feel like it does n't accurately describe that a client instance is the code that has the key as you described in the previous comment . 
 In the Cambridge dictionary ( UK ) : instance = " a particular situation , event , or fact , especially an example of something that happens generally " In US English (   ) : " a step , stage , or situation viewed as part of a process or series of events " Which is what we try to convey here . The client instance ( and the fields that provide context / facts on device posture etc . ) corresponds to a specific situation ( e.g a build ) or step ( e.g. a version ) and the underlying key might be rotated at some point ( as part of a serie of events ) . So the use of literal English is fine here . It just happens that in computing , and devops / architecture especially , many people use " instance " with the meaning closer to " copy " ( but again , of the same version / build / config / etc ) 
 for a multi - homed client where the parts have shared access to the key material , the entire structure would be considered the " instance " of the client . If that can be made more clear than the current text , quoted above , please make a suggestion ! 
 said " It is called client instance because it represents a specific occurrence of a client software ( like a specific version or a specific build target ) , but this has currently nothing to do with the deployment model . " During a client refresh both the old and new clients will existing at the same time . Sometimes for several days . this could be related to section 2.3.1 & .2 issue 9 section 2.3.1 & .2 are not clear to me , but i am not sure that what i am reading is even the current state of the doc . also 2.3.2 uses the term " proof method " which does not seem to be defined in the spec , 
 yes , there have been some changes based on your feedback ( and Yaron and  ) . We 're back on using " client " , and " instance " is used in the text when it is necessary . Generally speaking , the markdown file is considered the official version , but there might be several concurrent updates through PRs are the same time . Regarding your point . During a client refresh , there might be both the old and new client software indeed . But a specific user would use only one of them normally ( typically for a mobile app , an OTA replaces the old app by the new one / for  it 's usually quite simple ) . Or do you see other cases ? Proof method here refers to section 8 . " The form of proof that the RC will use when presenting the key to the AS . The valid values of this field and the processing requirements for each are detailed in Section 8 . " If other items are not clear , we 'll need to clarify them ( or possibly make some changes ) . Please let us know . 
 I guess the question about other cases depends on whether GNAP decides to support sessions that live over a single browser tab instance . For example , in registration or renewal events i may be sent a email that requires me to click to agree . When I click i will get whatever and wherever the DNS sends me . Now it would be possible to add state to the email link , but now we are getting WAY TOO DEEP into the actual working of the site . The client ID needs some level of persistence that transcends the specific server , time zone , s / w , whatever , that might exist at the other end of a click . BTW , in another thread we discussed consent removal . That would most likely require a client ID consistence . 
 Netlify deployed gnap - core - protocol - editors - draft as draft https://--gnap - core - protocol - editors- 
 Continuing a Grant Request :  's note : We need to have a secure way to rotate the key used for the continuation here . In most cases this will be a rotation for the client instance , since a client without an instance record would likely just present a new key for a new request . In that case it could go with the client management , above - but it does n't necessarily have to be . 
 See my comment on pull request I think we need to find a single rotation recovery method . I collected my ideas here : 
 This is close to what I was thinking about . I would also add as a reference what is doing on key rotation , for discussion purposes . 
 Key rotation is now handled on the continuation access token , not as part of the grant update . See 
 Could you answer on and other comments in this PR ? Thank you . 
 what do you mean by " more or less gracefully " ? 
 you can omit " more or less gracefully " , I wanted to know if  allows to address the use case I provided and 
 Indeed the idea currently is that previous - key is replaced by the new key , for all what 's coming afterwards . I know of some systems that allow a delay during which both versions coexist , is that what you 're after ? 
 There are plenty of systems where both , or even more versions coexist until an administrator or a client itself decides to remove / invalidate previous keys . That 's correct . The same approach arguably is even way more valuable for . BTW , are you planning to allow them to rotate their own keys ? You are writing these specs , and IMO , you still have time to add & embed these features into the core of GNAP . 
 This brings a more consistent text overall . The  vs client software works well and has been changed throughout the text . I do n't see any additional change to make right now . FYI , this PR has been highlighted in the suggested process to establish a new terminology ( see ) . I 'll include in the proposal that we keep the term client instance -  ( possibly updating the associated definition ) . The only downside is the potential confusion with CI / CD ( but usually the term is used in full , people do n't tend to refer to  only ) , so that should be fine . Then it will be interesting to check group consensus for the entire terminology section , including the item discussed here .
Mailing list commentary: Hi all , I hope you have a great Thanksgiving Regarding terminology : it 's important work so that we all talk the same language and people understand the spec more easily . Ideally the editors ( and the chairs I believe ) would like to be able to consolidate consensus on terminology over a relatively short period of time , so that we can all focus on the core of the spec ( a lot of work to do , and this should n't stop us from going forward ) . The suggested process is the following : 0 ) refer to issue 29 and the wiki for the latest state of discussion ( serves as a temporary consolidation of terms , before we can make a PR ) . It also provides guidance . This gives us a good starting point . A scenario could be that we chose to reuse the current terms ( and update definitions ) , if we do n't see concrete proposals that get positive support from the working group . That 's the fallback strategy . But we 'd like to start a phase where we open the discussion more broadly and see whether we can do better . 1 ) please send complete proposals on the mailing list , during the next 2 weeks . Discussions on a single term wo n't be accepted at this point in time , the idea being that we 'd like to start from a relatively coherent set of terms and definitions . Feel free also to comment on the mailing list on other people 's proposals : do you agree ? do you object ? are there terms we should remove / add ? ( please be as factual as possible in your explanations ) . The more we can see consensus emerging at this stage the easier it will be . Please also have a look at " External sources " , because we do n't want to live in a vacuum . If existing definitions exist in our field , either reuse it if it fits our purpose , or explain why you need to change it . Please do n't use a well - known term in a completely different way . 2 ) then the editors will propose a consolidated wiki The editors will update the wiki , considering : ideas and feedback sent on the mailing list , but also consistency with the charter 's objectives and the rest of the work . Depending on how it goes , we might already submit a PR ( especially if we see a high level of agreement - > short track ) . Then we 'll enter into the regular 1 week period to gather comments . Further discussion / explanations could be managed in a live interim IETF meeting ( since this would be free , a maximum of people would be able to participate ) . At that stage , we should at least agree on the terms used , but their definitions might still change . 3 ) If required : focused / detailed issues on specific terms We 'll limit the time spent in this last step , with a defined deadline . 4 ) W6 Publish a PR and gather consensus for the duration of the work for the core spec Then hopefully we can achieve consensus from the group . At that point we 'll publish a new draft version with the changes , probably in sync with a formal IETF meeting ( depends on how chairs / editors want to proceed , nothing has been defined yet , it 's just a personal opinion ) . In addition to what will be displayed in the wiki , the PR will most probably change the structure of the document , to include a dedicated section for terminology . It will also update the rest of the document accordingly ( editing work only ) . If new terminology requires specific design work , it shall be handled as separate issues , but does n't preclude from including it already in the terminology . Example : suppose we 'd want to separate the AS into a backend and a frontend ( Interaction Server ) , we could introduce the term but the implications of that would have to be dealt separately . This example shows that terminology has potential broader impacts . 5 ) Before the final draft of the spec is published , I would expect a last review of the definitions at the end ( but the terms would n't change ) , so that we make sure it is still up to date . Later , if extensions to the core spec require specific terms , we 'll then be able to expand the terminology . To summarize , the goal of this process is to keep going forward , and avoid discussions that very possibly would never end otherwise . We feel it 's very important to get that right in an early stage , so we hope you 'll get involved in the process . Please comment on this process if needed . We 're waiting for your contributions on the terminology for the next 2 weeks .   : as highlighted by , the editors have a PR running that concerns the [ Client Instance ] ( ) . This is linked to work being done on the core spec itself . We 'll see if we need to adjust it as a result , but it does n't preclude from making the current version more consistent .
Paragraph (version A):
Manages the requested delegations for the RO.  The AS issues
tokens and directly delegated information to the RC.  The AS is
defined by its grant endpoint, a single URL that accepts a POST
request with a JSON payload.  The AS could also have other
endpoints, including interaction endpoints and user code
endpoints, and these are introduced to the RC as needed during the
delegation process.
Paragraph (version A):
Requests tokens from the AS and uses tokens at the RS.  An
instance of the RC software is identified by its key, which can be
known to the AS prior to the first request.  The AS determines
which policies apply to a given RC, including what it can request
and on whose behalf.
Paragraph (version A):
Accepts tokens from the RC issued by the AS and serves delegated
resources on behalf of the RO.  There could be multiple RSs
protected by the AS that the RC will call.
Paragraph (version A):
Authorizes the request from the RC to the RS, often interactively
at the AS.
Paragraph (version A):
Operates and interacts with the RC.
Paragraph (version A):
Multiple roles can be fulfilled by the same party, and a given party
can switch roles in different instances of the protocol.  For
example, the RO and RQ in many instances are the same person, where a
user is authorizing the RC to act on their own behalf at the RS.  In
this case, one party fulfills both of the RO and RQ roles, but the
roles themselves are still defined separately from each other to
allow for other use cases where they are fulfilled by different
parties.
Paragraph (version A):
For another example, in some complex scenarios, an RS receiving
requests from one RC can act as an RC for a downstream secondary RS
in order to fulfill the original request.  In this case, one piece of
software is both an RS and an RC from different perspectives, and it
fulfills these roles separately as far as the overall protocol is
concerned.
Paragraph (version A):
A single role need not be deployed as a monolithic service.  For
example, An RC could have components that are installed on the RQ's
device as well as a back-end system that it communicates with.  If
both of these components participate in the delegation protocol, they
are both considered part of the RC.
Paragraph (version A):
For another example, an AS could likewise be built out of many
constituent components in a distributed architecture.  The component
that the RC calls directly could be different from the component that
the the RO interacts with to drive consent, since API calls and user
interaction have different security considerations in many
environments.  Furthermore, the AS could need to collect identity
claims about the RO from one system that deals with user attributes
while generating access tokens at another system that deals with
security rights.  From the perspective of GNAP, all of these are
pieces of the AS and together fulfill the role of the AS as defined
by the protocol.
Paragraph (version A):
A credential representing a set of access rights delegated to the
RC.  The access token is created by the AS, consumed and verified
by the RS, and issued to and carried by the RC.  The contents and
format of the access token are opaque to the RC.
Paragraph (version A):
A cryptographic element binding a request to a holder of the key.
Access tokens and RC instances can be associated with specific
keys.
Paragraph (version A):
A protected API served by the RS and accessed by the RC.  Access
to this resource is delegated by the RO as part of the grant
process.
Paragraph (version A):
Information about the RO that is returned directly to the RC from
the AS without the RC making a separate call to an RS.  Access to
this information is delegated by the RO as part of the grant
process.
Paragraph (version B):
For another example, in some complex scenarios, an RS receiving
requests from one client instance can act as a client instance for a
downstream secondary RS in order to fulfill the original request.  In
this case, one piece of software is both an RS and a client instance
from different perspectives, and it fulfills these roles separately
as far as the overall protocol is concerned.
Paragraph (version A):
Note that a connection between roles in this process does not
necessarily indicate that a specific protocol message is sent across
the wire between the components fulfilling the roles in question, or
that a particular step is required every time.  For example, for an
RC interested in only getting subject information directly, and not
calling an RS, all steps involving the RS below do not apply.
Paragraph (version B):
Note that a connection between roles in this process does not
necessarily indicate that a specific protocol message is sent across
the wire between the components fulfilling the roles in question, or
that a particular step is required every time.  For example, for a
client instance interested in only getting subject information
directly, and not calling an RS, all steps involving the RS below do
not apply.
Paragraph (version A):
In this example flow, the RC is a web application that wants access
to resources on behalf of the current user, who acts as both the
requesting party (RQ) and the resource owner (RO).  Since the RC is
capable of directing the user to an arbitrary URL and receiving
responses from the user's browser, interaction here is handled
through front-channel redirects using the user's browser.  The RC
uses a persistent session with the user to ensure the same user that
is starting the interaction is the user that returns from the
interaction.
Paragraph (version A):
The RC establishes a verifiable session to the user, in the role
of the RQ.
Paragraph (version A):
The RC request.  The RC indicates that it can request-interact-
redirect and request-interact-callback.  The RC stores
verification information for its callback in the session created
in (1).
Paragraph (version A):
The AS determines that interaction is needed and response with a
response-interact-redirect and response-interact-callback in (7).
The AS also includes information the RC will need to response-
continue in (8).  The AS associates this continuation information
with an ongoing request that will be referenced in (4), (6), and
(8).
Paragraph (version A):
The RC stores the verification and continuation information from
(3) in the session from (1).  The RC then interaction-redirect
given by the AS in (3).  The user's browser loads the interaction
redirect URL.  The AS loads the pending request based on the
incoming URL generated in (3).
Paragraph (version A):
When the AS is done interacting with the user, the AS interaction-
callback to the RC using the callback URL provided in (2).  The
callback URL is augmented with an interaction reference that the
AS associates with the ongoing request created in (2) and
referenced in (4).  The callback URL is also augmented with a hash
of the security information provided in (2) and (3).  The RC loads
the verification information from (2) and (3) from the session
created in (1).  The RC interaction-hash based on this information
and continues only if the hash validates.  Note that the RC needs
to ensure that the parameters for the incoming request match those
that it is expecting from the session created in (1).  The RC also
needs to be prepared for the RQ never being returned to the RC and
handle time outs appropriately.
Paragraph (version A):
The RC loads the continuation information from (3) and sends the
interaction reference from (7) in a request to continue-after-
interaction.  The AS validates the interaction reference ensuring
that the reference is associated with the request being continued.
Paragraph (version A):
In this example flow, the RC is a device that is capable of
presenting a short, human-readable code to the user and directing the
user to enter that code at a known URL.  The RC is not capable of
presenting an arbitrary URL to the user, nor is it capable of
accepting incoming HTTP requests from the user's browser.  The RC
polls the AS while it is waiting for the RO to authorize the request.
The user's interaction is assumed to occur on a secondary device.  In
this example it is assumed that the user is both the RQ and RO,
though the user is not assumed to be interacting with the RC through
the same web browser used for interaction at the AS.
Paragraph (version A):
The RC request.  The RC indicates that it can request-interact-
usercode.
Paragraph (version A):
The AS determines that interaction is needed and response with a
response-interact-usercode.  This could optionally include a URL
to direct the user to, but this URL should be static and so could
be configured in the RC's documentation.  The AS also includes
information the RC will need to response-continue in (8) and (10).
The AS associates this continuation information with an ongoing
request that will be referenced in (4), (6), (8), and (10).
Paragraph (version A):
The RC stores the continuation information from (2) for use in (8)
and (10).  The RC then interaction-redirect given by the AS in
(2).
Paragraph (version A):
The user's directs their browser to the user code URL.  This URL
is stable and can be communicated via the RC's documentation, the
AS documentation, or the RC software itself.  Since it is assumed
that the RO will interact with the AS through a secondary device,
the RC does not provide a mechanism to launch the RO's browser at
this URL.
Paragraph (version A):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the RC to response-continue at a future
time through additional polled continuation requests.  This
response can include updated continuation information as well as
information regarding how long the RC should wait before calling
again.  The RC replaces its stored continuation information from
the previous response (2).  Note that the AS may need to determine
that the RO has not approved the request in a sufficient amount of
time and return an appropriate error to the RC.
Paragraph (version A):
The RC continues to continue-poll with the new continuation
information in (9).
Paragraph (version B):
When the AS is done interacting with the user, the AS interaction-
callback to the client instance using the callback URL provided in
(2).  The callback URL is augmented with an interaction reference
that the AS associates with the ongoing request created in (2) and
referenced in (4).  The callback URL is also augmented with a hash
of the security information provided in (2) and (3).  The client
instance loads the verification information from (2) and (3) from
the session created in (1).  The client instance interaction-hash
based on this information and continues only if the hash
validates.  Note that the client instance needs to ensure that the
parameters for the incoming request match those that it is
expecting from the session created in (1).  The client instance
also needs to be prepared for the RQ never being returned to the
client instance and handle time outs appropriately.
Paragraph (version B):
The client instance loads the continuation information from (3)
and sends the interaction reference from (7) in a request to
continue-after-interaction.  The AS validates the interaction
reference ensuring that the reference is associated with the
request being continued.
Paragraph (version B):
The client instance request.  The client instance indicates that
it can request-interact-usercode.
Paragraph (version B):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the client instance to response-continue
at a future time through additional polled continuation requests.
This response can include updated continuation information as well
as information regarding how long the client instance should wait
before calling again.  The client instance replaces its stored
continuation information from the previous response (2).  Note
that the AS may need to determine that the RO has not approved the
request in a sufficient amount of time and return an appropriate
error to the client instance.
Paragraph (version B):
The client instance continues to continue-poll with the new
continuation information in (9).
Paragraph (version A):
In this example flow, the RQ and RO roles are fulfilled by different
parties, and the RO does not interact with the RC.  The AS reaches
out asynchronously to the RO during the request process to gather the
RO's authorization for the RC's request.  The RC polls the AS while
it is waiting for the RO to authorize the request.
Paragraph (version A):
The RC request.  The RC does not send any interactions modes to
the server, indicating that it does not expect to interact with
the RO.  The RC can also signal which RO it requires authorization
from, if known, by using the request-user.
Paragraph (version A):
The AS determines that interaction is needed, but the RC cannot
interact with the RO.  The AS response with the information the RC
will need to response-continue in (6) and (8), including a signal
that the RC should wait before checking the status of the request
again.  The AS associates this continuation information with an
ongoing request that will be referenced in (3), (4), (5), (6), and
(8).
Paragraph (version A):
The RO authorizes the pending request from the RC.
Paragraph (version A):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the RC to response-continue at a future
time through additional polling.  This response can include
refreshed credentials as well as information regarding how long
the RC should wait before calling again.  The RC replaces its
stored continuation information from the previous response (2).
Note that the AS may need to determine that the RO has not
approved the request in a sufficient amount of time and return an
appropriate error to the RC.
Paragraph (version A):
The RC continues to continue-poll with the new continuation
information from (7).
Paragraph (version A):
In this example flow, the AS policy allows the RC to make a call on
its own behalf, without the need for a RO to be involved at runtime
to approve the decision.  Since there is no explicit RO, the RC does
not interact with an RO.
Paragraph (version A):
The RC request.  The RC does not send any interactions modes to
the server.
Paragraph (version A):
The AS determines that the request is been authorized, the AS
grants access to the information in the form of response-token and
response-subject to the RC.
Paragraph (version A):
In this example flow, the RC receives an access token to access a
resource server through some valid GNAP process.  The RC uses that
token at the RS for some time, but eventually the access token
expires.  The RC then gets a new access token by rotating the expired
access token at the AS using the token's management URL.
Paragraph (version A):
The RC request.
Paragraph (version A):
The RC use-access-token to the RS.  The RS validates the token and
returns an appropriate response for the API.
Paragraph (version A):
When the access token is expired, the RS responds to the RC with
an error.
Paragraph (version A):
The RC calls the token management URI returned in (2) to rotate-
access-token.  The RC presents the access token as well as the
appropriate key.
Paragraph (version A):
The AS validates the rotation request including the signature and
keys presented in (5) and returns a response-token-single.  The
response includes a new access token and can also include updated
token management information, which the RC will store in place of
the values returned in (2).
Paragraph (version A):
To start a request, the RC sends RFC8259 document with an object as
its root.  Each member of the request object represents a different
aspect of the RC's request.  Each field is described in detail in a
section below.
Paragraph (version A):
Describes the rights that the RC is requesting for one or more
access tokens to be used at RS's.
Paragraph (version A):
Describes the information about the RO that the RC is requesting
to be returned directly in the response from the AS.
Paragraph (version A):
Describes the RC that is making this request, including the key
that the RC will use to protect this request and any continuation
requests at the AS and any user-facing information about the RC
used in interactions at the AS.
Paragraph (version A):
Describes the modes that the RC has for allowing the RO to
interact with the AS and modes for the RC to receive updates when
interaction is complete.
Paragraph (version A):
Identifies named extension capabilities that the RC can use,
signaling to the AS which extensions it can use.
Paragraph (version A):
Identifies a previously-existing grant that the RC is extending
with this request.
Paragraph (version B):
The AS determines that interaction is needed, but the client
instance cannot interact with the RO.  The AS response with the
information the client instance will need to response-continue in
(6) and (8), including a signal that the client instance should
wait before checking the status of the request again.  The AS
associates this continuation information with an ongoing request
that will be referenced in (3), (4), (5), (6), and (8).
Paragraph (version B):
The RO authorizes the pending request from the client instance.
Paragraph (version B):
The client instance continues to continue-poll with the new
continuation information from (7).
Paragraph (version A):
If the RC is requesting one or more access tokens for the purpose of
accessing an API, the RC MUST include a "resources" field.  This
field MUST be an array (for a request-resource-single) or an object
(for request-resource-multiple), as described in the following
sections.
Paragraph (version A):
When requesting an access token, the RC MUST send a "resources" field
containing a JSON array.  The elements of the JSON array represent
rights of access that the RC is requesting in the access token.  The
requested access is the sum of all elements within the array.
Paragraph (version A):
The RC declares what access it wants to associated with the resulting
access token using objects that describe multiple dimensions of
access.  Each object contains a "type" property that determines the
type of API that the RC is calling.
Paragraph (version B):
When requesting an access token, the client instance MUST send a
"resources" field containing a JSON array.  The elements of the JSON
array represent rights of access that the client instance is
requesting in the access token.  The requested access is the sum of
all elements within the array.
Paragraph (version B):
The client instance declares what access it wants to associated with
the resulting access token using objects that describe multiple
dimensions of access.  Each object contains a "type" property that
determines the type of API that the client instance is calling.
Paragraph (version A):
The types of actions the RC will take at the RS as an array of
strings.  For example, an RC asking for a combination of "read"
and "write" access.
Paragraph (version A):
The kinds of data available to the RC at the RS's API as an array
of strings.  For example, an RC asking for access to raw "image"
data and "metadata" at a photograph API.
Paragraph (version A):
Instead of sending an request-resource-single, a RC MAY send a string
known to the AS or RS representing the access being requested.  Each
string SHOULD correspond to a specific expanded object representation
at the AS.
Paragraph (version A):
This functionality is similar in practice to OAuth 2's "scope"
parameter RFC6749, where a single string represents the set of access
rights requested by the RC.  As such, the reference string could
contain any valid OAuth 2 scope value as in example-oauth2.  Note
that the reference string here is not bound to the same character
restrictions as in OAuth 2's "scope" definition.
Paragraph (version A):
When requesting multiple access tokens, the resources field is a JSON
object.  The names of the JSON object fields are token identifiers
chosen by the RC, and MAY be any valid string.  The values of the
JSON object fields are JSON arrays representing a single access token
request, as specified in request-resource-single.
Paragraph (version A):
While the AS is ultimately in control of how tokens are returned and
bound to the RC, sometimes the RC has context about what it can
support that can affect the AS's response.  This specification
defines several flags that are passed as request-resource-reference.
Paragraph (version A):
The RC wishes to support multiple simultaneous access tokens
through the token rotation process.  When the RC rotate-access-
token, the AS does not invalidate the previous access token.  The
old access token continues to remain valid until such time as it
expires or is revoked through other means.
Paragraph (version A):
In this non-normative example, the requested access token is to be
bound to the client's key and should be kept during rotation.
Paragraph (version A):
If the RC is requesting information about the RO from the AS, it
sends a "subject" field as a JSON object.  This object MAY contain
the following fields (or additional fields defined in IANA).
Paragraph (version A):
When sending a non-continuation request to the AS, the RC MUST
identify itself by including the "client" field of the request and by
signing the request as described in binding-keys.  Note that for a
continue-request, the RC instance is identified by its association
with the request being continued and so this field is not sent under
those circumstances.
Paragraph (version A):
When RC information is sent by value, the "client" field of the
request consists of a JSON object with the following fields.
Paragraph (version A):
The public key of the RC to be used in this request as described
in request-key.  This field is REQUIRED.
Paragraph (version A):
An identifier string that the AS can use to identify the software
comprising this instance of the RC.  The contents and format of
this field are up to the AS.  This field is OPTIONAL.
Paragraph (version B):
When client instance information is sent by value, the "client" field
of the request consists of a JSON object with the following fields.
Paragraph (version A):
The RC MUST prove possession of any presented key by the "proof"
mechanism associated with the key in the request.  Proof types are
defined in IANA and an initial set of methods is described in
binding-keys.
Paragraph (version A):
Note that the AS MAY know the RC's public key ahead of time, and the
AS MAY apply different policies to the request depending on what has
been registered against that key.  If the same public key is sent by
value on subsequent access requests, the AS SHOULD treat these
requests as coming from the same RC software instance for purposes of
identification, authentication, and policy application.  If the AS
does not know the RC's public key ahead of time, the AS MAY accept or
reject the request based on AS policy, attestations within the client
request, and other mechanisms.
Paragraph (version A):
If the RC has an instance identifier that the AS can use to determine
appropriate key information, the RC can send this value in the
"instance_id" field.  The instance identifier MAY be assigned to an
RC instance at runtime through the response-dynamic-handles or MAY be
obtained in another fashion, such as a static registration process at
the AS.
Paragraph (version A):
An identifier string that the AS can use to identify the
particular instance of this RC.  The content and structure of this
identifier is opaque to the RC.
Paragraph (version A):
If there are no additional fields to send, the RC MAY send the
instance identifier as a direct reference value in lieu of the
object.
Paragraph (version A):
If the RC instance is identified in this manner, the registered key
for the RC MAY be a symmetric key known to the AS.  The RC MUST NOT
send a symmetric key by value in the request, as doing so would
expose the key directly instead of proving possession of it.
Paragraph (version A):
The RC key MUST be a public key in at least one supported format and
MUST be applicable to the proofing mechanism used in the request.  If
the key is sent in multiple formats, all the keys MUST be the same.
The key presented in this field MUST be the key used to sign the
request.
Paragraph (version A):
The form of proof that the RC will use when presenting the key to
the AS.  The valid values of this field and the processing
requirements for each are detailed in binding-keys.  This field is
REQUIRED.
Paragraph (version A):
If the RC has additional information to display to the RO during any
interactions at the AS, it MAY send that information in the "display"
field.  This field is a JSON object that declares information to
present to the RO during any interactive sequences.
Paragraph (version A):
The AS SHOULD use these values during interaction with the RO.  The
values are for informational purposes only and MUST NOT be taken as
authentic proof of the RC's identity or source.  The AS MAY restrict
display values to specific RC instances, as identified by their keys
in request-client.
Paragraph (version A):
If the presented key is known to the AS and is associated with a
single instance of the RC software, the process of presenting a key
and proving possession of that key is sufficient to authenticate the
RC to the AS.  The AS MAY associate policies with the RC software
identified by this key, such as limiting which resources can be
requested and which interaction methods can be used.  For example,
only specific RCs with certain known keys might be trusted with
access tokens without the AS interacting directly with the RO as in
example-no-user.
Paragraph (version A):
The presentation of a key allows the AS to strongly associate
multiple successive requests from the same RC with each other.  This
is true when the AS knows the key ahead of time and can use the key
to authenticate the RC software, but also if the key is ephemeral and
created just for this series of requests.  As such the AS MAY allow
for RCs to make requests with unknown keys.  This pattern allows for
ephemeral RCs, such as single-page applications, and RCs with many
individual instances, such as mobile applications, to generate their
own key pairs and use them within the protocol without having to go
through a separate registration step.  The AS MAY limit which
capabilities are made available to RCs with unknown keys.  For
example, the AS could have a policy saying that only previously-
registered RCs can request particular resources, or that all RCs with
unknown keys have to be interactively approved by an RO.
Paragraph (version A):
If the RC knows the identity of the RQ through one or more
identifiers or assertions, the RC MAY send that information to the AS
in the "user" field.  The RC MAY pass this information by value or by
reference.
Paragraph (version B):
If the client instance has additional information to display to the
RO during any interactions at the AS, it MAY send that information in
the "display" field.  This field is a JSON object that declares
information to present to the RO during any interactive sequences.
Paragraph (version B):
If the presented key is known to the AS and is associated with a
single instance of the client software, the process of presenting a
key and proving possession of that key is sufficient to authenticate
the client instance to the AS.  The AS MAY associate policies with
the client instance identified by this key, such as limiting which
resources can be requested and which interaction methods can be used.
For example, only specific client instances with certain known keys
might be trusted with access tokens without the AS interacting
directly with the RO as in example-no-user.
Paragraph (version B):
The presentation of a key allows the AS to strongly associate
multiple successive requests from the same client instance with each
other.  This is true when the AS knows the key ahead of time and can
use the key to authenticate the client instance, but also if the key
is ephemeral and created just for this series of requests.  As such
the AS MAY allow for client instances to make requests with unknown
keys.  This pattern allows for ephemeral client instances, such as
single-page applications, and client software with many individual
long-lived instances, such as mobile applications, to generate key
pairs per instance and use the keys within the protocol without
having to go through a separate registration step.  The AS MAY limit
which capabilities are made available to client instances with
unknown keys.  For example, the AS could have a policy saying that
only previously-registered client instances can request particular
resources, or that all client instances with unknown keys have to be
interactively approved by an RO.
Paragraph (version A):
If the AS trusts the RC to present verifiable assertions, the AS MAY
decide, based on its policy, to skip interaction with the RO, even if
the RC provides one or more interaction modes in its request.
Paragraph (version A):
User reference identifiers can be dynamically response-dynamic-
handles to allow the RC to represent the same RQ to the AS over
subsequent requests.
Paragraph (version A):
If the RC has a reference for the RQ at this AS, the RC MAY pass that
reference as a string.  The format of this string is opaque to the
RC.
Paragraph (version A):
User reference identifiers are not intended to be human-readable user
identifiers or structured assertions.  For the RC to send either of
these, use the full request-user instead.
Paragraph (version A):
Many times, the AS will require interaction with the RO in order to
approve a requested delegation to the RC for both resources and
direct claim information.  Many times the RQ using the RC is the same
person as the RO, and the RC can directly drive interaction with the
AS by redirecting the RQ on the same device, or by launching an
application.  Other times, the RC can provide information to start
the RO's interaction on a secondary device, or the RC will wait for
the RO to approve the request asynchronously.  The RC could also be
signaled that interaction has completed by the AS making callbacks.
To facilitate all of these modes, the RC declares the means that it
can interact using the "interact" field.
Paragraph (version A):
Indicates that the RC can direct the RQ to an arbitrary URL at the
AS for interaction.
Paragraph (version A):
Indicates that the RC can launch an application on the RQ's device
for interaction.
Paragraph (version A):
Indicates that the RC can receive a callback from the AS after
interaction with the RO has concluded.
Paragraph (version A):
Indicates that the RC can communicate a human-readable short code
to the RQ for use with a stable URL at the AS.
Paragraph (version A):
In this non-normative example, the RC is indicating that it can
request-interact-redirect the RQ to an arbitrary URL and can receive
a request-interact-callback through a browser request.
Paragraph (version A):
In this non-normative example, the RC is indicating that it can
display a request-interact-usercode and direct the RQ to an request-
interact-short 255 characters, but it cannot accept a callback.
Paragraph (version A):
If the RC does not provide a suitable interaction mechanism, the AS
cannot contact the RO asynchronously, and the AS determines that
interaction is required, then the AS SHOULD return an error since the
RC will be unable to complete the request without authorization.
Paragraph (version A):
The AS SHOULD apply suitable timeouts to any interaction mechanisms
provided, including user codes and redirection URLs.  The RC SHOULD
apply suitable timeouts to any callback URLs.
Paragraph (version A):
If the RC is capable of directing the RQ to a URL defined by the AS
at runtime, the RC indicates this by sending the "redirect" field
with the boolean value "true".  The means by which the RC will
activate this URL is out of scope of this specification, but common
methods include an HTTP redirect, launching a browser on the RQ's
device, providing a scannable image encoding, and printing out a URL
to an interactive console.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a redirect interaction response response-interact-redirect.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a redirect interaction response with short URL response-
interact-redirect.
Paragraph (version A):
If the RC can open a URL associated with an application on the RQ's
device, the RC indicates this by sending the "app" field with boolean
value "true".  The means by which the RC determines the application
to open with this URL are out of scope of this specification.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns an app interaction response with an app URL payload response-
interact-app.
Paragraph (version A):
If the RC is capable of receiving a message from the AS indicating
that the RO has completed their interaction, the RC indicates this by
sending the "callback" field.  The value of this field is an object
containing the following members.
Paragraph (version A):
REQUIRED.  Unique value to be used in the calculation of the
"hash" query parameter sent to the callback URL, must be
sufficiently random to be unguessable by an attacker.  MUST be
generated by the RC as a unique value for this request.
Paragraph (version A):
REQUIRED.  The callback method that the AS will use to contact the
RC.  Valid values include "redirect" request-interact-callback-
redirect and "push" request-interact-callback-push, with other
values defined by IANA.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a nonce for use in validating response-interact-callback.
Requests to the callback URI MUST be processed as described in
interaction-finalize, and the AS MUST require presentation of an
interaction callback reference as described in continue-after-
interaction.
Paragraph (version A):
A callback "method" value of "redirect" indicates that the RC will
expect a call from the RO's browser using the HTTP method GET as
described in interaction-callback.
Paragraph (version A):
Requests to the callback URI MUST be processed by the RC as described
in interaction-callback.
Paragraph (version A):
Since the incoming request to the callback URL is from the RO's
browser, this method is usually used when the RO and RQ are the same
entity.  As such, the RC MUST ensure the RQ is present on the request
to prevent substitution attacks.
Paragraph (version A):
A callback "method" value of "push" indicates that the RC will expect
a call from the AS directly using the HTTP method POST as described
in interaction-pushback.
Paragraph (version A):
Requests to the callback URI MUST be processed by the RC as described
in interaction-pushback.
Paragraph (version A):
Since the incoming request to the callback URL is from the AS and not
from the RO's browser, the RC MUST NOT require the RQ to be present
on the incoming HTTP request.
Paragraph (version A):
If the RC is capable of displaying or otherwise communicating a
short, human-entered code to the RO, the RC indicates this by sending
the "user_code" field with the boolean value "true".  This code is to
be entered at a static URL that does not change at runtime, as
described in response-interact-usercode.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a user code and interaction URL as specified in interaction-
usercode.
Paragraph (version A):
If the RC knows the RQ's locale and language preferences, the RC can
send this information to the AS using the "ui_locales" field with an
array of locale strings as defined by RFC5646.
Paragraph (version B):
Requests to the callback URI MUST be processed by the client instance
as described in interaction-callback.
Paragraph (version B):
Requests to the callback URI MUST be processed by the client instance
as described in interaction-pushback.
Paragraph (version A):
If the RC supports extension capabilities, it MAY present them to the
AS in the "capabilities" field.  This field is an array of strings
representing specific extensions and capabilities, as defined by
IANA.
Paragraph (version A):
If the RC has a reference handle from a previously granted request,
it MAY send that reference in the "existing_grant" field.  This field
is a single string consisting of the "value" of the "access_token"
returned in a previous request's response-continue.
Paragraph (version A):
A single access token that the RC can use to call the RS on behalf
of the RO.
Paragraph (version A):
Multiple named access tokens that the RC can use to call the RS on
behalf of the RO.
Paragraph (version A):
An identifier this RC instance can use to identify itself when
making future requests.
Paragraph (version A):
An identifier this RC instance can use to identify its current RQ
when making future requests.
Paragraph (version A):
REQUIRED.  The URI at which the RC can make continuation requests.
This URI MAY vary per request, or MAY be stable at the AS if the
AS includes an access token.  The RC MUST use this value exactly
as given when making a continue-request.
Paragraph (version A):
RECOMMENDED.  The amount of time in integer seconds the RC SHOULD
wait after receiving this continuation handle and calling the URI.
Paragraph (version A):
This field SHOULD be returned when interaction is expected, to allow
the RC to follow up after interaction has been concluded.
Paragraph (version A):
If the AS has successfully granted one or more access tokens to the
RC, the AS responds with either the "access_token" or the
"multiple_access_token" field.  The AS MUST NOT respond with both the
"access_token" and "multiple_access_token" fields.
Paragraph (version A):
If the RC has requested a single access token and the AS has granted
that access token, the AS responds with the "access_token" field.
The value of this field is an object with the following properties.
Paragraph (version A):
REQUIRED.  The value of the access token as a string.  The value
is opaque to the RC.  The value SHOULD be limited to ASCII
characters to facilitate transmission over HTTP headers within
other protocols without requiring additional encoding.
Paragraph (version A):
OPTIONAL.  The management URI for this access token.  If provided,
the RC MAY manage its access token as described in token-
management.  This management URI is a function of the AS and is
separate from the RS the RC is requesting access to.  This URI
MUST NOT include the access token value and SHOULD be different
for each access token issued in a request.
Paragraph (version A):
RECOMMENDED.  A description of the rights associated with this
access token, as defined in request-resource-single.  If included,
this MUST reflect the rights associated with the issued access
token.  These rights MAY vary from what was requested by the RC.
Paragraph (version A):
OPTIONAL.  The number of seconds in which the access will expire.
The RC MUST NOT use the access token past this time.  An RS MUST
NOT accept an access token past this time.  Note that the access
token MAY be revoked by the AS or RS at any point prior to its
expiration.
Paragraph (version A):
REQUIRED.  The key that the token is bound to.  If the boolean
value "true" is used, the token is bound to the request-key in its
request for access.  If the boolean value "false" is used, the
token is a bearer token with no key bound to it.  Otherwise, the
key MUST be an object or string in a format described in request-
key, describing a public key to which the RC can use the
associated private key.  The RC MUST be able to dereference or
process the key information in order to be able to sign the
request.
Paragraph (version A):
The following non-normative example shows a single access token bound
to the RC's key, which was presented using the detached-jws binding
method.
Paragraph (version A):
If the RC request-resource-multiple, the AS MUST NOT respond with a
single access token structure unless the RC sends the "split_token"
flag as described in request-resource-flag.
Paragraph (version A):
If the RC has requested multiple access tokens and the AS has granted
at least one of them, the AS responds with the
"multiple_access_tokens" field.  The value of this field is a JSON
object, and the property names correspond to the token identifiers
chosen by the RC in the request-resource-multiple.  The values of the
properties of this object are access tokens as described in response-
token-single.
Paragraph (version A):
Each access token corresponds to the named resources arrays in the
RC's request-resource-multiple.
Paragraph (version B):
If the client instance has requested a single access token and the AS
has granted that access token, the AS responds with the
"access_token" field.  The value of this field is an object with the
following properties.
Paragraph (version A):
If the RC request-resource-single, the AS MUST NOT respond with the
multiple access token structure unless the RC sends the "split_token"
flag as described in request-resource-flag.
Paragraph (version A):
If the RC has indicated a request-interact, and the AS has determined
that interaction is both supported and necessary, the AS responds to
the RC with any of the following values in the "interact" field of
the response.  There is no preference order for interaction modes in
the response, and it is up to the RC to determine which ones to use.
All supported interaction methods are included in the same "interact"
object.
Paragraph (version A):
Callback to an RC URL after interaction is completed.
Paragraph (version A):
The AS MUST NOT respond with any interaction mode that the RC did not
indicate in its request.  The AS MUST NOT respond with any
interaction mode that the AS does not support.  Since interaction
responses include secret or unique information, the AS SHOULD respond
to each interaction mode only once in an ongoing request,
particularly if the RC continue-modify.
Paragraph (version A):
If the RC indicates that it can request-interact-redirect and the AS
supports this mode for the RC's request, the AS responds with the
"redirect" field, which is a string containing the URL to direct the
RQ to.  This URL MUST be unique for the request and MUST NOT contain
any security-sensitive information.
Paragraph (version A):
The RC sends the RQ to the URL to interact with the AS.  The RC MUST
NOT alter the URL in any way.  The means for the RC to send the RQ to
this URL is out of scope of this specification, but common methods
include an HTTP redirect, launching the system browser, displaying a
scannable code, or printing out the URL in an interactive console.
Paragraph (version A):
If the RC indicates that it can request-interact-app and the AS
supports this mode for the RC's request, the AS responds with the
"app" field, which is a string containing the URL to direct the RQ
to.  This URL MUST be unique for the request and MUST NOT contain any
security-sensitive information.
Paragraph (version A):
The RC launches the URL as appropriate on its platform, and the means
for the RC to launch this URL is out of scope of this specification.
The RC MUST NOT alter the URL in any way.  The RC MAY attempt to
detect if an installed application will service the URL being sent
before attempting to launch the application URL.
Paragraph (version A):
If the RC indicates that it can request-interact-callback and the AS
supports this mode for the RC's request, the AS responds with a
"callback" field containing a nonce that the RC will use in
validating the callback as defined in interaction-callback.
Paragraph (version A):
When the RO completes interaction at the AS, the AS MUST call the
RC's callback URL using the method indicated in the request-interact-
callback as described in interaction-callback.
Paragraph (version A):
If the AS returns a "callback" nonce, the RC MUST NOT continue a
grant request before it receives the associated interaction reference
on the callback URI.
Paragraph (version A):
If the RC indicates that it can request-interact-usercode and the AS
supports this mode for the RC's request, the AS responds with a
"user_code" field.  This field is an object that contains the
following members.
Paragraph (version B):
If the client instance has indicated a request-interact, and the AS
has determined that interaction is both supported and necessary, the
AS responds to the client instance with any of the following values
in the "interact" field of the response.  There is no preference
order for interaction modes in the response, and it is up to the
client instance to determine which ones to use.  All supported
interaction methods are included in the same "interact" object.
Paragraph (version B):
The AS MUST NOT respond with any interaction mode that the client
instance did not indicate in its request.  The AS MUST NOT respond
with any interaction mode that the AS does not support.  Since
interaction responses include secret or unique information, the AS
SHOULD respond to each interaction mode only once in an ongoing
request, particularly if the client instance continue-modify.
Paragraph (version A):
RECOMMENDED.  The interaction URL that the RC will direct the RO
to.  This URL MUST be stable at the AS such that RCs can be
statically configured with it.
Paragraph (version A):
The RC MUST communicate the "code" to the RQ in some fashion, such as
displaying it on a screen or reading it out audibly.  The "code" is a
one-time-use credential that the AS uses to identify the pending
request from the RC.  When the RO interaction-usercode into the AS,
the AS MUST determine the pending request that it was associated
with.  If the AS does not recognize the entered code, the AS MUST
display an error to the user.  If the AS detects too many
unrecognized codes entered, it SHOULD display an error to the user.
Paragraph (version A):
The RC SHOULD also communicate the URL if possible to facilitate user
interaction, but since the URL should be stable, the RC should be
able to safely decide to not display this value.  As this interaction
mode is designed to facilitate interaction via a secondary device, it
is not expected that the RC redirect the RQ to the URL given here at
runtime.  Consequently, the URL needs to be stable enough that a RC
could be statically configured with it, perhaps referring the RQ to
the URL via documentation instead of through an interactive means.
If the RC is capable of communicating an arbitrary URL to the RQ,
such as through a scannable code, the RC can use the request-
interact-redirect mode for this purpose instead of or in addition to
the user code mode.
Paragraph (version A):
If information about the RO is requested and the AS grants the RC
access to that data, the AS returns the approved information in the
"subject" response field.  This field is an object with the following
OPTIONAL properties.
Paragraph (version A):
Timestamp as an ISO8610 date string, indicating when the
identified account was last updated.  The RC MAY use this value to
determine if it needs to request updated profile information
through an identity API.  The definition of such an identity API
is out of scope for this specification.
Paragraph (version A):
Subject identifiers returned by the AS SHOULD uniquely identify the
RO at the AS.  Some forms of subject identifier are opaque to the RC
(such as the subject of an issuer and subject pair), while others
forms (such as email address and phone number) are intended to allow
the RC to correlate the identifier with other account information at
the RC.  The RC MUST NOT request or use any returned subject
identifiers for communication purposes (see request-subject).  That
is, a subject identifier returned in the format of an email address
or a phone number only identifies the RO to the AS and does not
indicate that the AS has validated that the represented email address
or phone number in the identifier is suitable for communication with
the current user.  To get such information, the RC MUST use an
identity protocol to request and receive additional identity claims.
While request-oidc-claims specifies one such method, other identity
protocols could also be used on top of GNAP to convey this
information and the details of an identity protocol and associated
schema are outside the scope of this specification.
Paragraph (version A):
Many parts of the RC's request can be passed as either a value or a
reference.  The use of a reference in place of a value allows for a
client to optimize requests to the AS.
Paragraph (version A):
Some references, such as for the request-instance or the request-
resource-reference, can be managed statically through an admin
console or developer portal provided by the AS or RS.  The developer
of the RC can include these values in their code for a more efficient
and compact request.
Paragraph (version A):
If desired, the AS MAY also generate and return some of these
references dynamically to the RC in its response to facilitate
multiple interactions with the same software.  The RC SHOULD use
these references in future requests in lieu of sending the associated
data value.  These handles are intended to be used on future
requests.
Paragraph (version A):
Dynamically generated handles are string values that MUST be
protected by the RC as secrets.  Handle values MUST be unguessable
and MUST NOT contain any sensitive information.  Handle values are
opaque to the RC.
Paragraph (version B):
Many parts of the client instance's request can be passed as either a
value or a reference.  The use of a reference in place of a value
allows for a client instance to optimize requests to the AS.
Paragraph (version A):
A string value used to represent the information in the "client"
object that the RC can use in a future request, as described in
request-instance.
Paragraph (version A):
A string value used to represent the current user.  The RC can use
in a future request, as described in request-user-reference.
Paragraph (version A):
If the AS determines that the request cannot be issued for any
reason, it responds to the RC with an error message.
Paragraph (version A):
The RC did not respect the timeout in the wait response.
Paragraph (version A):
If the RC request-interact, and the AS determines that interaction is
required and responds to one or more of the RC's interaction modes,
the RC SHOULD initiate one of the returned response-interact.
Paragraph (version A):
When the RO is directed to the AS through the response-interact-
redirect mode, the AS can interact with the RO through their web
browser to authenticate the user as an RO and gather their consent.
Note that since the RC does not add any parameters to the URL, the AS
MUST determine the grant request being referenced from the URL value
itself.  If the URL cannot be associated with a currently active
request, the AS MUST display an error to the RO and MUST NOT attempt
to redirect the RO back to any RC even if a request-interact-
callback.
Paragraph (version A):
The interaction URL MUST be reachable from the RO's browser, though
note that the RO MAY open the URL on a separate device from the RC
itself.  The interaction URL MUST be accessible from an HTTP GET
request, and MUST be protected by HTTPS or equivalent means.
Paragraph (version A):
With this method, it is common for the RO to be the same party as the
RQ, since the RC has to communicate the redirection URI to the RQ.
Paragraph (version A):
When the RO is directed to the AS through the response-interact-
usercode mode, the AS can interact with the RO through their web
browser to collect the user code, authenticate the user as an RO, and
gather their consent.  Note that since the URL itself is static, the
AS MUST determine the grant request being referenced from the user
code value itself.  If the user code cannot be associated with a
currently active request, the AS MUST display an error to the RO and
MUST NOT attempt to redirect the RO back to any RC even if a request-
interact-callback.
Paragraph (version A):
The user code URL MUST be reachable from the RO's browser, though
note that the RO MAY open the URL on a separate device from the RC
itself.  The user code URL MUST be accessible from an HTTP GET
request, and MUST be protected by HTTPS or equivalent means.
Paragraph (version A):
While it is common for the RO to be the same party as the RQ, since
the RC has to communicate the user code to someone, there are cases
where the RQ and RO are separate parties and the authorization
happens asynchronously.
Paragraph (version A):
When the RC successfully launches an application through the
response-interact-app, the AS interacts with the RO through that
application to authenticate the user as the RO and gather their
consent.  The details of this interaction are out of scope for this
specification.
Paragraph (version A):
Upon completing an interaction with the RO, if a response-interact-
callback mode is available with the current request, the AS MUST
follow the appropriate method at the end of interaction to allow the
RC to continue.  If this mode is not available, the AS SHOULD
instruct the RO to return to their RC software upon completion.  Note
that these steps still take place in most error cases, such as when
the RO has denied access.  This pattern allows the RC to potentially
recover from the error state without restarting the request from
scratch by modifying its request or providing additional information
directly to the AS.
Paragraph (version A):
The AS MUST calculate a hash value based on the RC and AS nonces and
the interaction reference, as described in interaction-hash.  The RC
will use this value to validate the return call from the AS.
Paragraph (version A):
When using the response-interact-callback with the "redirect" method,
the AS signals to the RC that interaction is complete and the request
can be continued by directing the RO (in their browser) back to the
RC's callback URL sent in request-interact-callback-redirect.
Paragraph (version A):
The AS secures this callback by adding the hash and interaction
reference as query parameters to the RC's callback URL.
Paragraph (version A):
When receiving the request, the RC MUST parse the query parameters to
calculate and validate the hash value as described in interaction-
hash.  If the hash validates, the RC sends a continuation request to
the AS as described in continue-after-interaction using the
interaction reference value received here.
Paragraph (version A):
When using the response-interact-callback with the "push" method, the
AS signals to the RC that interaction is complete and the request can
be continued by sending an HTTP POST request to the RC's callback URL
sent in request-interact-callback-push.
Paragraph (version A):
When receiving the request, the RC MUST parse the JSON object and
validate the hash value as described in interaction-hash.  If the
hash validates, the RC sends a continuation request to the AS as
described in continue-after-interaction using the interaction
reference value received here.
Paragraph (version A):
The "hash" parameter in the request to the RC's callback URL ties the
front channel response to an ongoing request by using values known
only to the parties involved.  This security mechanism allows the RC
to protect itself against several kinds of session fixation and
injection attacks.  The AS MUST always provide this hash, and the RC
MUST validate the hash when received.
Paragraph (version A):
To calculate the "hash" value, the party doing the calculation first
takes the "nonce" value sent by the RC in the request-interact-
callback, the AS's nonce value from response-interact-callback, and
the "interact_ref" sent to the RC's callback URL.  These three values
are concatenated to each other in this order using a single newline
character as a separator between the fields.  There is no padding or
whitespace before or after any of the lines, and no trailing newline
character.
Paragraph (version A):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter of the "callback".  If the
"hash_method" value is not present in the RC's request, the algorithm
defaults to "sha3".
Paragraph (version A):
While it is possible for the AS to return a response with all the
RC's requested information (including response-token and response-
subject), it's more common that the AS and the RC will need to
communicate several times over the lifetime of an access grant.  This
is often part of facilitating user-interaction, but it could also be
used to allow the AS and RC to continue negotiating the parameters of
the request.
Paragraph (version A):
The ability to continue an already-started request allows the RC to
perform several important functions, including presenting additional
information from interaction, modifying the initial request, and
getting the current state of the request.
Paragraph (version A):
For continuation functions that require the RC to send a message
body, the body MUST be a JSON object.
Paragraph (version A):
When the AS responds to the RC's "callback" parameter as in
interaction-callback, this response includes an interaction
reference.  The RC MUST include that value as the field
"interact_ref" in a POST request to the continuation URI.
Paragraph (version A):
Since the interaction reference is a one-time-use value as described
in interaction-callback, if the RC needs to make additional
continuation calls after this request, the RC MUST NOT include the
interaction reference.  If the AS detects an RC submitting the same
interaction reference multiple times, the AS MUST return an error and
SHOULD invalidate the ongoing request.
Paragraph (version A):
With this example, the RC can not make an additional continuation
request because a "continue" field is not included.
Paragraph (version A):
When the RC does not include a "callback" parameter, the RC will
often need to poll the AS until the RO has authorized the request.
To do so, the RC makes a POST request to the continuation URI as in
continue-after-interaction, but does not include a message body.
Paragraph (version A):
The response MAY contain any newly-created response-token or newly-
released response-subject.  The response MAY contain a new response-
continue as described above.  If a "continue" field is included, it
SHOULD include a "wait" field to facilitate a reasonable polling rate
by the RC.  The response SHOULD NOT contain response-interact.
Paragraph (version A):
For example, if the request has not yet been authorized by the RO,
the AS could respond by telling the RC to make another continuation
request in the future.  In this example, a new, unique access token
has been issued for the call, which the RC will use in its next
continuation request.
Paragraph (version B):
For continuation functions that require the client instance to send a
message body, the body MUST be a JSON object.
Paragraph (version B):
With this example, the client instance can not make an additional
continuation request because a "continue" field is not included.
Paragraph (version B):
For example, if the request has not yet been authorized by the RO,
the AS could respond by telling the client instance to make another
continuation request in the future.  In this example, a new, unique
access token has been issued for the call, which the client instance
will use in its next continuation request.
Paragraph (version A):
The RC might need to modify an ongoing request, whether or not tokens
have already been issued or claims have already been released.  In
such cases, the RC makes an HTTP PATCH request to the continuation
URI and includes any fields it needs to modify.  Fields that aren't
included in the request are considered unchanged from the original
request.
Paragraph (version A):
The RC MAY include the "interact" field as described in request-
interact.  Inclusion of this field indicates that the RC is capable
of driving interaction with the RO, and this field replaces any
values from a previous request.  The AS MAY respond to any of the
interaction responses as described in response-interact, just like it
would to a new request.
Paragraph (version A):
The AS replaces the previous "resources" from the first request,
allowing the AS to determine if any previously-granted consent
already applies.  In this case, the AS would likely determine that
reducing the breadth of the requested access means that new access
tokens can be issued to the RC.  The AS would likely revoke
previously-issued access tokens that had the greater access rights
associated with them.
Paragraph (version A):
For another example, the RC initially requests read-only access but
later needs to step up its access.  The initial request could look
like this example.
Paragraph (version A):
This allows the RC to make an eventual continuation call.  The RC
later realizes that it now needs "write" access in addition to the
"read" access.  Since this is an expansion of what it asked for
previously, the RC also includes a new interaction section in case
the AS needs to interact with the RO again to gather additional
authorization.  Note that the RC's nonce and callback are different
from the initial request.  Since the original callback was already
used in the initial exchange, and the callback is intended for one-
time-use, a new one needs to be included in order to use the callback
again.
Paragraph (version A):
From here, the AS can determine that the RC is asking for more than
it was previously granted, but since the RC has also provided a
mechanism to interact with the RO, the AS can use that to gather the
additional consent.  The protocol continues as it would with a new
request.  Since the old access tokens are good for a subset of the
rights requested here, the AS might decide to not revoke them.
However, any access tokens granted after this update process are new
access tokens and do not modify the rights of existing access tokens.
Paragraph (version A):
If the RC needs to get the current state of an ongoing grant request,
it makes an HTTP GET request to the continuation URI.  This request
MUST NOT alter the grant request in any fashion, including causing
the issuance of new access tokens or modification of interaction
parameters.
Paragraph (version B):
For another example, the client instance initially requests read-only
access but later needs to step up its access.  The initial request
could look like this example.
Paragraph (version B):
This allows the client instance to make an eventual continuation
call.  The client instance later realizes that it now needs "write"
access in addition to the "read" access.  Since this is an expansion
of what it asked for previously, the client instance also includes a
new interaction section in case the AS needs to interact with the RO
again to gather additional authorization.  Note that the client
instance's nonce and callback are different from the initial request.
Since the original callback was already used in the initial exchange,
and the callback is intended for one-time-use, a new one needs to be
included in order to use the callback again.
Paragraph (version B):
From here, the AS can determine that the client instance is asking
for more than it was previously granted, but since the client
instance has also provided a mechanism to interact with the RO, the
AS can use that to gather the additional consent.  The protocol
continues as it would with a new request.  Since the old access
tokens are good for a subset of the rights requested here, the AS
might decide to not revoke them.  However, any access tokens granted
after this update process are new access tokens and do not modify the
rights of existing access tokens.
Paragraph (version A):
If the RC wishes to cancel an ongoing grant request, it makes an HTTP
DELETE request to the continuation URI.
Paragraph (version A):
If an access token response includes the "manage" parameter as
described in response-token-single, the RC MAY call this URL to
manage the access token with any of the actions defined in the
following sections.  Other actions are undefined by this
specification.
Paragraph (version A):
The access token being managed acts as the access element for its own
management API.  The RC MUST present proof of an appropriate key
along with the access token.
Paragraph (version A):
If the token is a bearer token, the RC MUST present proof of the same
request-key as described in binding-keys.
Paragraph (version A):
The AS MUST validate the proof and assure that it is associated with
either the token itself or the RC the token was issued to, as
appropriate for the token's presentation type.
Paragraph (version A):
The RC makes an HTTP POST to the token management URI, sending the
access token in the appropriate header and signing the request with
the appropriate key.
Paragraph (version A):
The AS validates that the token presented is associated with the
management URL, that the AS issued the token to the given RC, and
that the presented key is appropriate to the token.
Paragraph (version A):
If the access token has expired, the AS SHOULD honor the rotation
request to the token management URL since it is likely that the RC is
attempting to refresh the expired token.  To support this, the AS MAY
apply different lifetimes for the use of the token in management vs.
its use at an RS.  An AS MUST NOT honor a rotation request for an
access token that has been revoked, either by the AS or by the RC
through the revoke-access-token.
Paragraph (version B):
The access token being managed acts as the access element for its own
management API.  The client instance MUST present proof of an
appropriate key along with the access token.
Paragraph (version B):
The AS MUST validate the proof and assure that it is associated with
either the token itself or the client instance the token was issued
to, as appropriate for the token's presentation type.
Paragraph (version A):
If the RC wishes to revoke the access token proactively, such as when
a user indicates to the RC that they no longer wish for it to have
access or the RC application detects that it is being uninstalled,
the RC can use the token management URI to indicate to the AS that
the AS should invalidate the access token for all purposes.
Paragraph (version A):
The RC makes an HTTP DELETE request to the token management URI,
presenting the access token and signing the request with the
appropriate key.
Paragraph (version A):
If the key presented is associated with the token (or the RC, in the
case of a bearer token), the AS MUST invalidate the access token, if
possible, and return an HTTP 204 response code.
Paragraph (version A):
Though the AS MAY revoke an access token at any time for any reason,
the token management function is specifically for the RC's use.  If
the access token has already expired or has been revoked through
other means, the AS SHOULD honor the revocation request to the token
management URL as valid, since the end result is still the token not
being usable.
Paragraph (version A):
The method the RC uses to send an access token to the RS depends on
the value of the "key" and "proof" parameters in response-token-
single.
Paragraph (version B):
If the client instance wishes to revoke the access token proactively,
such as when a user indicates to the client instance that they no
longer wish for it to have access or the client instance application
detects that it is being uninstalled, the client instance can use the
token management URI to indicate to the AS that the AS should
invalidate the access token for all purposes.
Paragraph (version B):
The client instance makes an HTTP DELETE request to the token
management URI, presenting the access token and signing the request
with the appropriate key.
Paragraph (version B):
If the key presented is associated with the token (or the client
instance, in the case of a bearer token), the AS MUST invalidate the
access token, if possible, and return an HTTP 204 response code.
Paragraph (version A):
If the "key" value is the boolean "true", the access token MUST be
sent to the RS using the same key and proofing mechanism that the RC
used in its initial request.
Paragraph (version A):
The header of the JWS MUST contain the "kid" field of the key bound
to this RC for this request.  The JWS header MUST contain an "alg"
field appropriate for the key identified by kid and MUST NOT be
"none".
Paragraph (version A):
The RC presents the JWS as the body of the request along with a
content type of "application/jose".  The AS MUST extract the payload
of the JWS and treat it as the request body for further processing.
Paragraph (version A):
This method is indicated by "mtls" in the "proof" field.  The RC
presents its client certificate during TLS negotiation with the
server (either AS or RS).  The AS or RS takes the thumbprint of the
client certificate presented during mutual TLS negotiation and
compares that thumbprint to the thumbprint presented by the RC
application as described in RFC8705 section 3.
Paragraph (version A):
This method is indicated by "httpsig" in the "proof" field.  The RC
creates an HTTP Signature header as described in I-D.ietf-httpbis-
message-signatures section 4.  The RC MUST calculate and present the
Digest header as defined in RFC3230 and include this header in the
signature.
Paragraph (version A):
By design, the protocol minimizes the need for any pre-flight
discovery.  To begin a request, the RC only needs to know the
endpoint of the AS and which keys it will use to sign the request.
Everything else can be negotiated dynamically in the course of the
protocol.
Paragraph (version A):
REQUIRED.  The full URL of the AS's grant request endpoint.  This
MUST match the URL the RC used to make the discovery request.
Paragraph (version A):
OPTIONAL.  A list of the AS's capabilities.  The values of this
result MAY be used by the RC in the request-capabilities of the
request.
Paragraph (version A):
The information returned from this method is for optimization
purposes only.  The AS MAY deny any request, or any portion of a
request, even if it lists a capability as supported.  For example, a
given RC can be registered with the "mtls" key proofing mechanism,
but the AS also returns other proofing methods, then the AS will deny
a request from that RC using a different proofing mechanism.
Paragraph (version A):
The RC calls the RS with its access token.
Paragraph (version A):
The RS introspects the access token value at the AS.  The RS signs
the request with its own key (not the RC's key or the token's
key).
Paragraph (version A):
The AS validates the token value and the RC's request and returns
the introspection response for the token.
Paragraph (version A):
The RS fulfills the request from the RC.
Paragraph (version A):
Some architectures require an RS to act as an RC and request a
derived access token for a secondary RS.  This internal token is
issued in the context of the incoming access token.
Paragraph (version A):
The RC calls RS1 with an access token.
Paragraph (version A):
RS1 presents that token to the AS to get a derived token for use
at RS2.  RS1 indicates that it has no ability to interact with the
RO.  RS1 signs its request with its own key, not the token's key
or the RC's key.
Paragraph (version A):
RS1 fulfills the call from RC.
Paragraph (version A):
If the RC calls an RS without an access token, or with an invalid
access token, the RS MAY respond to the RC with an authentication
header indicating that GNAP needs to be used to access the resource.
The address of the GNAP endpoint MUST be sent in the "as_uri"
parameter.  The RS MAY additionally return a resource reference that
the RC MAY use in its request-resource.  This resource reference
handle SHOULD be sufficient for at least the action the RC was
attempting to take at the RS.  The RS MAY use the rs-register-
resource-handle to register a new resource handle, or use a handle
that has been pre-configured to represent what the AS is protecting.
The content of this handle is opaque to the RS and the RC.
Paragraph (version A):
The RC then makes a call to the "as_uri" as described in request,
with the value of "resource" as one of the members of a "resources"
array request-resource-single.  The RC MAY request additional
resources and other information, and MAY request multiple access
tokens.
Paragraph (version A):
When user information is passed to the RC, the AS needs to make sure
that it has the permission to do so.