index.md

ORCID Link Service

version: 0.1.0

The ORCID Link Service provides an API to enable the linking of a KBase user account to an ORCID account. This "link" consists of a Link Record which contains a KBase username, ORCID id, ORCID access token, and a few other fields. This link record allows KBase to create tools and services which utilize the ORCID api to view or modify certain aspects of a users ORCID profile.

Once connected, ORCID Link enables certain integrations, including:

• syncing your KBase profile from your ORCID profile
• creating and managing KBase public Narratives within your ORCID profile

Terms of Service

https://www.kbase.us/about/terms-and-conditions-v2/

Contact

KBase, Lawrence Berkeley National Laboratory, DOE
https://www.kbase.us/
engage@kbase.us

License

The MIT License https://github.com/kbase/kb_sdk/blob/develop/LICENSE.md

Usage

This document is primarily generated from the openapi interface generated by FastAPI.

The Endpoints section documents all REST endpoints, including the expected responses, input parameters and output JSON and type definitions.

The Types section defines all of the Pydantic models used in the codebase, most of which are in service of the input and output types mentioned above.

Issues

• Due to limitations of GitHub's markdown support, tables have two empty rows at the start of the header. This is due to the fact that GitHub does not allow any table formatting instructions, so we need to use the first two rows to establish the table and column widths.

Table of Contents

• Endpoints
  • misc
  • link
  • linking-sessions
  • orcid
  • works
• Types
• Glossary

Endpoints

jsonrpc

JSON-RPC 2.0 method

POST /api/v1

n/a

Input

none

Output

Status Code	Description	Type
200	Successful Response	_Response
210	[1010] Authorization Required	_ErrorResponse_AuthorizationRequiredError_
211	[1011] Not Authorized	_ErrorResponse_NotAuthorizedError_
212	[1020] Not Found	_ErrorResponse_NotFoundError_
213	[-32602] Invalid params Invalid method parameter(s)	ErrorResponse_InvalidParams
214	[-32601] Method not found The method does not exist / is not available	ErrorResponse_MethodNotFound
215	[-32700] Parse error Invalid JSON was received by the server	ErrorResponse_ParseError
216	[-32600] Invalid Request The JSON sent is not a valid Request object	ErrorResponse_InvalidRequest
217	[-32603] Internal error Internal JSON-RPC error	ErrorResponse_InternalError
default	Default Response	none

---

misc

Miscellaneous operations

GET /docs

Get API Documentation

Provides a web interface to the auto-generated API docs.

Input

none

Output

Status Code	Description	Type
200	Successfully returned the api docs	text/html
404	Not Found	none

---

link

Access to and control over stored ORCID Links

linking-sessions

OAuth integration and internal support for creating ORCID Links.

The common path element is /linking-sessions.

Some of the endpoints are "browser interactive", meaning that the links are followed directly by the browser, rather than being used within Javascript code.

GET /linking-sessions/{session_id}/oauth/start

Start Linking Session

This endpoint is designed to be used directly by the browser. It is the "start" of the ORCID OAuth flow. If the provided session id is found and the associated session record is still in the initial state, it will initiate the OAuth flow by redirecting the browser to an endpoint at ORCID.

Starts a "linking session", an interactive OAuth flow the end result of which is an access_token stored at KBase for future use by the user.

Input

Name	Description	Type	In
session_id	The linking session id	string	path
return_link	A url to redirect to after the entire linking is complete; not to be confused with the ORCID OAuth flow's redirect_url	n/a	query
skip_prompt	Whether to prompt for confirmation of linking	boolean	query
ui_options	Opaque string of ui options	string	query
kbase_session	KBase auth token taken from a cookie named 'kbase_session'	string	cookie
kbase_session_backup	KBase auth token taken from a cookie named 'kbase_session_backup. Required in the KBase production environment since the prod ui and services operate on different hosts; the primary cookie, kbase_session, is host-based so cannot be read by a prod service.	string	cookie

Output

Status Code	Description	Type
302	Redirect to ORCID if a valid linking session, back to KBase in the case of an error	none
401	KBase auth token absent or invalid	none
422	Input or output data does not comply with the API schema	none

---

GET /linking-sessions/oauth/continue

Continue Linking Session

This endpoint implements the handoff from from the ORCID authorization step in the ORCID OAuth flow. That is, it serves as the redirection target after the user has successfully completed their interaction with ORCID, at which they may have logged in and provided their consent to issuing the linking token to KBase.

Note that this is an interstitional endpoint, which does not have its own user interface. Rather, it redirects to kbase-ui when finished. If an error is encountered, it redirects to an error viewing endpoint in kbase-ui.

Input

Name	Description	Type	In
code	For a success case, contains an OAuth exchange code parameter	n/a	query
state	For a success case, contains an OAuth state parameter	n/a	query
error	For an error case, contains an error code parameter	n/a	query
kbase_session	KBase auth token taken from a cookie named 'kbase_session'	string	cookie
kbase_session_backup	KBase auth token taken from a cookie named 'kbase_session_backup. Required in the KBase production environment since the prod ui and services operate on different hosts; the primary cookie, kbase_session, is host-based so cannot be read by a prod service.	string	cookie

Output

Status Code	Description	Type
302	Redirect to the continuation page; or error page	none
401	Linking requires authorization; same meaning as standard auth 401, but caught and issued in a different manner	none
422	Input or output data does not comply with the API schema	none

---

orcid

Direct access to ORCID via ORCID Link

works

Add, remove, update 'works' records for a user's ORCID Account

Types

This section presents all types defined via FastAPI (Pydantic). They are ordered alphabetically, which is fine for looking them up, but not for their relationships.

TODO: a better presentation of related types

AuthorizationRequiredError

Name	Type	Required
code	integer
message	string

InternalError

Name	Type	Required
code	integer
message	string

InvalidParams

Name	Type	Required
code	integer
message	string
data	Any Of _ErrorData__Error_ null

InvalidRequest

Name	Type	Required
code	integer
message	string
data	Any Of _ErrorData__Error_ null

MethodNotFound

Name	Type	Required
code	integer
message	string

NotAuthorizedError

Name	Type	Required
code	integer
message	string

NotFoundError

Name	Type	Required
code	integer
message	string

ParseError

Name	Type	Required
code	integer
message	string

_Error

Name	Type	Required
loc	array	✓
msg	string	✓
type	string	✓
ctx	Any Of object null

ErrorData__Error

Name	Type	Required
errors	Any Of array null

ErrorResponse_AuthorizationRequiredError

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	AuthorizationRequiredError	✓

ErrorResponse_InternalError

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	InternalError	✓

ErrorResponse_InvalidParams

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	InvalidParams	✓

ErrorResponse_InvalidRequest

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	InvalidRequest	✓

ErrorResponse_MethodNotFound

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	MethodNotFound	✓

ErrorResponse_NotAuthorizedError

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	NotAuthorizedError	✓

ErrorResponse_NotFoundError

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	NotFoundError	✓

ErrorResponse_ParseError

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
error	ParseError	✓

_Request

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0
id	Any Of string integer
method	string	✓
params	object

_Response

Name	Type	Required
jsonrpc	Const const 2.0 title Jsonrpc default 2.0 example 2.0	✓
id	Any Of string integer	✓
result	object	✓

Glossary

ORCID

Open Researcher and Contributor ID

Public link record

The record used internally to associate a KBase User Account with an ORCID Account, with sensitive information such as tokens removed. Represented by the type LinkRecordPublic

-fin-