Glossary of Terms

Definitions for some of the terms used in the OAuth API documentation.

A

access token
See OAuth access token.
Ajax
An abbreviation for Advanced JavaScript and XML—A term for a set of related web development techniques that can be used together to update parts of a webpage without reloading the entire page.
anonymous user
A user who is browsing the platform without logging in.
API
A key resource in the Akana API Platform. An API provides a business with a way of using the Internet to extend business capabilities to connect with new customers in new ways. In this context an API is a Web service exposed outside the enterprise, typically using RESTful design principles, and often with JSON content.
app
An app (application) is a piece of software that delivers specific capabilities to its users. In the context of the Akana API Platform, an app is a piece of software that consumes one or more APIs.
app team member
One of the roles defined in the Akana API Platform is that of the app team member. Each app most have at least one team member and can have more. An app team member initiates contract requests, such as API access requests, moderates the app's Board, and views and manages trouble tickets relating to the app. The app team member can also view performance and usage data for the app's API usage, and can invite others to be team members for the same app. All app team members have the same rights.
AppID
When a user registers an app in the Akana API Platform, the app is assigned an AppID. The AppID is the unique identifier for the app within the platform. All API calls include the AppID.
Assertion
See SAML assertion.
Assertion Consumer Service (ACS) endpoint
In SAML, the endpoint where the service provider will receive SAML assertions from the identity provider.
Artifact Resolution Service (ARS)
In SAML, a service that you must set up if you want to use the HTTP Artifact binding (supported for single sign-on SAML response messages). You can then use the service to retrieve the full message using the artifact. See HTTP Artifact.
AtmoAuthToken
A tenant-specific cookie. This is the platform's authorization token. This cookie indicates the level of access allowed. It is valid only for 30 minutes and must be renewed at that time. It also includes other information, such as the APIs, apps, and groups the user is a member of. When any of this information changes, the token must be renewed.
Because the AtmoAuthToken includes a lot of information about the user, in some cases the token is long, and could potentially cause requests to fail if the server has a limitation on HTTP header length. For this reason, container configuration properties include authTokenMaxLength. When the AtmoAuthToken would be greater than the max length, the platform creates a mini auth token, and saves the full auth token in the database.
Authorization endpoint (OAuth)
See OAuth authorization endpoint.
Authorization header
The Authorization request header contains the username and password. It's sent by the client, to authenticate the client with the server. A client includes this header in its request after receiving a 401 Authentication Required response from the server. The Authorization header includes the authorization scheme and the authorization value. For more information, see OAuth 1.0a Authorization Header (reference article).
auto-connect
An API setting that allows a contract to be created automatically with the API when a new app is created. The auto-connect feature can be specified per environment and can also be limited to specific licenses.
avatar
Within the platform, an avatar is an image that can be associated with a resource such as an app, API, user, or API Context Group.

B

Base URL
In setting up the SAML identity provider in Policy Manager, the platform provides a specific URL to be used for instances where the Identity Provider, when encountering an error, returns the error response to the default Service Provider endpoint rather than just showing the error on the authentication page. PingFederate is an example of an Identity Provider that returns an error response in this way.
To construct the endpoint to be used for error responses, the platform needs to know the {protocol_scheme}://{host}:{por}> of the container where the SAML Web SSO domain is initialized. This is the base URL.
bearer token
Used in OAuth, the bearer token is a security token with the property that any party in possession of the token (the bearer) can use it. Using a bearer token does not require proof of possession of cryptographic key material (proof-of-possession).

C

CA SiteMinder
CA SiteMinder® is a popular commercial access management product. The platform supports use of CA SiteMinder for login or for OAuth support.
CER file
A message generated by a certificate authority in response to a request for a digital identity certificate.
When uploading app credentials, the app developer can upload either a CER file or a CSR file.
See also: CSR file.
claim (JWT)
In the context of JWT, a claim is "A piece of information asserted about a subject. A claim is represented as a name/value pair consisting of a Claim Name and a Claim Value." A Claim Name is always a string; a Claim Value can be any JSON value.
For more information, refer to the JWT Claims section of the JWT specification: http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#rfc.section.4.
claim (OpenID Connect)
In OpenID Connect a claim is a piece of information about an end-user, which is returned to the Relying Party by the OpenID Connect Identity Provider after both the end-user and the Relying Party have authenticated. The OpenID Connect specification defines some standard claims; additional claims can be added. Depending on the process flow that's supported by the Identity Provider and requested by the Relying Party, claims might be returned in the UserInfo Response from the UserInfo Endpoint, or in the ID Token from the Token Endpoint.
Examples of standard claims: given_name, family_name, email. For more information, refer to the Standard Claims section of the OpenID Connect specification.
CNAME
Abbreviation for Canonical Name. A CNAME identifies a unique domain name registered in the Domain Name System (DNS); for example, www.acmepaymentscorp.com. The domain name is mapped to an IP address.
When adding an API, the API definition includes CNAME, which is the hostname part of the URL which will be visible to app developers for the API. Typically you would register a CNAME (such as api.acmepaymentscorp.com) in your DNS for your API and then map it to the proxy hostname provided to you during signup (typically acmepaymentscorp.broker.soa.com).
Connect provider
In OpenID Connect, the identity provider is called the Connect provider.
connection
A relationship between resources in the Akana API Platform —such as the API access relationship between an app and an API that it's using.
Coordinated Universal Time (UTC)
Coordinated Universal Time (UTC), also called Zulu time, is the primary time standard in general use. It essentially equates to Greenwich Mean Time (GMT), but is more scientifically precise. In the Akana OAuth API, time values are represented in the standard UTC date/time format YYYY-MM-DDTHH:MM:SSZ. Example: 2013-12-31T15:45:00-04:00Z.
Epoch time, also called Unix time, is defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time; Thursday, 1 January 1970. In some cases we use this value in response messages, expressed in milliseconds.
CORS
Acronym for Cross-Origin Resource Sharing. CORS allows users to access resources from within the browser serving a web page, and defines a way in which the browser and the server can interact to determine whether or not to allow the cross-origin request.
The platform includes a policy, CORSAllowAll; if this policy is selected as part of an API definition, all cross-origin requests to the API are allowed.
CSR file
Acronym for Certificate Signing Request; a message sent to a certificate authority to request a digital identity certificate.
When uploading app credentials, the app developer can upload either a CER file or a CSR file.
Because the platform supports CSR import, the app developer does not need to get a signed certificate from a CA. Instead, the developer can generate a CSR from the key pair that he/she created, and can import that directly.
When a CSR is imported, the platform uses its internal Certificate Authority to create the CER from the request. Therefore, in order to support CER, the platform's own certificate authority must be configured.
See also: CER file.

D

denial of service policy
A policy that defines conditions for protecting against, and/or dealing with, a Denial of Service attack.
duration
The duration of a request or response message is expressed with the Duration data type in the format PnYnMnDTnHnMnS. For example, a message response time of P0Y0M0DT0H0M0.022S indicates 22 milliseconds. For an expanded definition of Duration, refer to Data Types.

E

Entity ID
In SAML, a unique identifier for an entity. A SAML entity can be a Service Provider or an Identity Provider.
As a service provider, you define the Entity ID. When setting up your account with the Identity Provider you must specify the Entity ID, which must be unique within the IdP so that the IdP can identify your Service Provider.
The Entity ID is used as the value of the {Issuer} element inside the SAML protocol message. In an authentication request, the {Issuer} element contains the Entity ID of the Service Provider; in the SAML response, it has the Entity ID of the Identity Provider.
From the perspective of the Service Provider, the Entity ID is analogous to the client_id in OAuth.
entity references
When an HTTP GET operation in the platform returns information in the form of an RSS channel, it very often includes entity references. Where an RSS item represents an object, the entity references include additional information about the object. For example, if the RSS channel returns information about an app version, the entity reference might include information about the app to which the app version belongs. All relevant relationships to the object returned in the RSS response are represented in the entity references.
enumeration (of users)
The term user enumeration, user enum, or simply enum refers to a security vulnerability that allows an unauthorized user to compile a list of valid user accounts that are authorized to log in to an application. For example, if an unauthorized user can try to sign up with an existing email address, and the application returns a message that an account already exists for that email address, the application is giving away information.
The platform includes enhanced security settings that can be activated to help prevent enumeration of users.
environment
An app/API contract can apply either to the Sandbox environment, which is a testing area, or the production environment.
epoch time
Epoch time, also called Unix time, is defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time; Thursday, 1 January 1970. In some cases the developer platform uses this value in response messages, expressed in milliseconds.
extended properties
The Extended Properties feature is an add-on feature, available for use with the Akana API Platform, that allows you to set up and use configurable custom properties, along with workflows based on those properties.
For installation information and links to additional resources see Installing the Extended Properties Feature.

F

favicon
A small icon, typically 16x16 pixels, associated with a website or a specific webpage.
Implementation varies, but typically the browser displays the favicon in the address bar, on the tab next to the page title, and next to the page's name in a list of bookmarks.
FDN
The Fully Distinguished Name of a platform member. This applies to federated members. To uniquely identify an item across federation members, the Relative Distinguished Name (RDN) is joined with the hosting federation member's name to create a Fully Distinguished Name (FDN).
federation
Two or more Akana API Platform tenants who have unified to create a community in which APIs can be shared by users of both tenants.
The systems that participate in a federation (federation members, tenants) share information without requiring duplication of that information in each member and without relinquishing control of the information. Developers who sign up as users of one federation member can access information from a second federation member directly, without the need for signup or authentication by the second member. A federation setup requires the establishment of a trust relationship between federation members.
forum entry
An individual content contribution by a specific user, to one of the forum types. A forum entry is essentially exactly the same as a Board item entry.
A forum entry is essentially exactly the same as a Board item entry. However, in the user interface,

H

HMAC
The HMAC hashing algorithm uses a symmetric key to create a hash for message security. HMAC can be used with cryptographic hash algorithms such as MD5 or SHA-1.
HTTP Artifact
One of the binding options supported by the SAML protocol. HTTP Artifact is useful in scenarios where the SAML requester and responder are using an HTTP user-agent and do not want to transmit the entire message, either for technical or security reasons. Instead, a SAML Artifact is sent, which is a unique ID for the full information. The IdP can then use the Artifact to retrieve the full information. The artifact issuer must maintain state while the artifact is pending.
HTTP Artifact sends the artifact as a query parameter.
Community Manager currently supports this binding option for SAML responses, but not for SAML requests.
HTTP POST
One of the binding options supported by the SAML protocol.
HTTP POST sends the message content as a POST parameter, in the payload.
Community Manager currently supports this binding option for SAML, for both requests and responses.
HTTP Redirect
One of the binding options supported by the SAML protocol.
When HTTP Redirect is used, the service provider redirects the user to the identity provider where the login happens, and the identity provider redirects the user back to the service provider. HTTP Redirect requires intervention by the User-Agent (the browser).
Community Manager currently supports this binding option for SAML requests.

I

ICAP server
Internet Content Adaptation Protocol (ICAP) is a protocol that is sometimes used to extend a transparent proxy server for HTTP services. One common usage is to designate an ICAP server that provides virus scanning services.
The anti-virus policy provided by the platform's underlying infrastructure allows designation of an ICAP server that will provide anti-virus functionality. Once the policy is in place, messages are routed to the ICAP server, scanned, and forwarded only if they pass the scan.
identity (app)
When adding an app version, you can specify a custom identity name for the app version. If no custom value is specified, in response messages this property defaults to the reverse of the RuntimeID, with a dash. For example, if the RuntimeID is 123456.acmepaymentscorp, the value for the Identity property would be open-123456.
identity provider
An identity provider (sometimes abbreviated as IdP) is an entity responsible for verifying user identity and issuing identity information, usually in the form of a token. A common example is a website that allows users to log in using a Facebook or Google identity; in this scenario, Facebook and Google are identity providers. In OpenID Connect, the identity provider is called the Connect provider.
In terms of SAML, the identity provider verifies the identity of the user in response to a request by the Service Provider, and then responds with a SAML assertion.
IdP
In SAML, abbreviation for Identity Provider.

J

JSON
An acronym for JavaScript Object Notation, JSON uses a subset of the JavaScript syntax to describe an object clearly and succinctly. One of the advantages of JSON over XML for API messages is that message content conveyed in the JSON format is much more concise than the same content conveyed in XML, consuming less bandwidth.
JSON Web Key
A JSON Web Key (JWK) is a JSON data structure that represents a cryptographic key (for example, an RSA key).
JSON Web Key Set
A JSON data structure that represents a set of JSON Web Keys.
JWK
See JSON Web Key.
JWT token (OpenID Connect)
Acronym for JSON Web Token. In the context of OpenID Connect, a JWT token is a compact, URL-safe means of representing claims to be sent from one party to another over the web. The claims in a JWT are encoded as a JSON object that is used either as the payload of a JSON Web Signature (JWS) structure or as the plain text of a JSON Web Encryption (JWE) structure. This enables the claims to be digitally signed and/or encrypted.
The OpenID Connect Provider can issue a JWT token from either the Authorization Endpoint or the Token Endpoint. This is one of the two ways offered by the OpenID Connect specification for the app to learn information about the end user. The other is by publishing a UserInfo endpoint.

L

LaaS
Lifecycle as a Service (LaaS) is a set of products from Akana that exposes Lifecycle Manager asset configuration as a service/API. LaaS provides a way to integrate Lifecycle Manager functionality into the Akana API Platform. Since Lifecycle Manager is more configurable, this facilitates the introduction of a more complex workflow, which can be used for purposes such as API governance.
LAAS includes two separate features:
label (for a ticket)
A label assigned to a ticket to indicate the ticket's priority rating.
LDAP
Acronym for Lightweight Directory Access Protocol, an open, industry-standard protocol used by the platform to support single sign-on.
Lifecycle Coordinator
Lifecycle Coordinator is a separate configurable component that coordinates promotion across multiple instances of API Platform tenants. It can be deployed standalone or can be co-located with a tenant (or multiple tenants in the SaaS environment). Lifecycle Coordinator governs the promotion process and the transfer of data between environments.
Lifecycle Repository
Lifecycle Repository is another name for the Extended Properties add-on component, available for use with the Akana API Platform, that allows you to set up and use configurable properties, along with workflows based on those properties. Configurable properties are supported for the following resource types: API, App, and User.
For installation information and links to additional resources see Installing the Extended Properties Feature.
login domain
A domain that platform users can use to log in to the platform. The platform itself is a login domain, but a specific instance of the platform might support additional login domains, such as Google and Facebook. Login domains are defined by the Site Admin as part of initial setup. Once it is set up, a login domain name cannot be changed.

M

MAC token
Acronym for Message Authentication Code. Used in OAuth 2.0, the MAC token is a security code that is typed in by the user of a computer to access an account or a portal. The code is attached to the message or request sent by the user. The MAC token attached to the message must be recognized by the receiving system in order to grant the user access. MAC tokens are commonly used in electronic funds transfer (EFT) transactions to maintain information integrity.

N

nonce
A nonce is a random string, uniquely generated by the client for each request. The nonce allows the server to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure-channel.
notification state
When a user first receives a notification, the notification state is Unread. Other valid notification states are: Read, Archived.

O

OAuth
OAuth is a popular Web security protocol that enables a user to grant permission to a third-party application to access the user's Web resources without sharing passwords or personal information. The third-party application first facilitates a connection to the holder of the Web resources so that the user can log in and approve the access. For example, User A could allow Site B, a subscription-only online training site, to have access to Account C, the user's credit card account, by authorizing a monthly debit of $25. User A would first sign in and approve the monthly debit. Site B could complete subsequent monthly debits without further interaction with User A; however, User A could cancel the access at any time. OAuth has been likened to a valet key on a car which gives access to certain features of the car without giving full access.
Essentially, OAuth allows a web-based or mobile application to use an API exposed by another web or mobile application without sharing passwords.
OAuth access token
In OAuth, an access token is essentially a pass, a credential that gives authorization to access the requested and approved resource or resources for as long as the access token remains valid. In some cases, access tokens can be renewed by means of a refresh token; in some cases they cannot. For more information, refer to the OAuth 2.0 specification (external site).
OAuth authorization code
With the OAuth 2.0 Authorization Code grant type, the resource owner (consumer; for example, the app user) is redirected to the authorization server and gives authorization for the app to access the resource. The authorization server then redirects the consumer back to the client app with an authorization code. The client app presents this authorization code, along with the app's authentication credentials, back to the authorization server, requesting an access token (and optionally a refresh token). The client then uses the access token to call the service on behalf of the resource owner. A refresh token can be used to extend the lifetime of this session.
An Authorization Code is a short-lived token issued to the client application by the authorization server upon successful authentication/authorization of an end-user (resource owner). The client application then uses the authorization code to request an access token from the authorization server.
OAuth authorization endpoint
The endpoint for the OAuth Authorization Server. This is the endpoint on the authorization server where the resource owner provides credentials, such as username and password, in and grants authorization to the client app to access the resources or a specified subset of the resources.
When setting up an OAuth domain, Site Admins must specify this value. Additionally, if an API is using a third-party OAuth provider rather than an OAuth domain set up on the platform, the API Admin must specify this value in the OAuth setup wizard.
Users connect to the authorization endpoint; apps connect to the token endpoint.
OAuth authorization server
In an OAuth implementation, the authorization server collects the resource owner's credentials, gets the resource owner's permission for the app to access the resources, and passes back the authorization token to the app so that the app can then access the resources.
OAuth authorization server URL
As part of setting up the OAuth domain, the Site Admin must specify the Authorization Server URL. This is the URL that the browser for the resource owner (app user) will be accessing for the OAuth grant. It is the URL at which the OAuth Provider accesses the requests, for both Authorization Endpoint and Token Endpoint.
The URL must be accessible to all the apps and end users that might use APIs that are referencing the OAuth domain. The Authorization Endpoint and Token Endpoint for OAuth 10.a and OAuth 2.0 will use different paths according to the specific OAuth version. Firewalls and DNS servers must be set up for this URL so that end users and apps can access the URL.
OAuth callback URL
Redirect URL. The URL to which the API sends the response message with the token.
OAuth grant types
OAuth 2.0 supports four different grant types; each has a different process flow. Grant types are designated as 2-legged or 3-legged depending on the number of parties involved. The 2-legged grant types are Client Credentials and Resource Owner Password Credentials; the three-legged grant types are Authorization Code and Implicit. The platform also supports an extension grant type. For more information, see OAuth Grant Type values.
OAuth grant types: 2-legged
The number of legs used to describe an OAuth request refers to the number of parties involved; 2-legged or 3-legged. When the client is also the resource owner, it is a 2-legged flow. OAuth 2.0 includes the following 2-legged grant types; Client Credentials and Resource Owner Password Credentials.
OAuth grant types: 3-legged
The number of legs used to describe an OAuth request refers to the number of parties involved. The most common process flow includes three parties; a client, a server, and a resource owner. This is a 3-legged flow. OAuth 2.0 includes the following 3-legged grant types; Authorization Code and Implicit.
OAuth grant types: Authorization Code
A 3-legged OAuth 2.0 grant type: An authorization code is returned to the client through a browser redirect after the resource owner gives consent to the OAuth Authorization Server. The client then exchanges the authorization code for an access token. Resource owner credentials are never exposed to the client app.
OAuth grant types: Client Credentials
A 2-legged OAuth 2.0 grant type: The client presents its own credentials to the OAuth Authorization Server in order to obtain an access token. This access token is either associated with the client's own resources, rather than a specific resource owner, or is associated with a resource owner for whom the client is otherwise authorized to act.
OAuth grant types: Implicit
A 3-legged OAuth 2.0 grant type: An access token is returned to the client through a browser redirect in response to the resource owner authorization request. This grant type is suitable for clients that do not support keeping client credentials confidential (for use in authenticating with the OAuth Authentication Server) such as client applications implemented in a browser using a scripting language like JavaScript.
OAuth grant types: Resource Owner Password Credentials
A 2-legged OAuth 2.0 grant type: The client collects the resource owner's password and exchanges it at the OAuth authorization server for an access token, and often also a refresh token. This grant type is suitable in cases where the resource owner has a trust relationship with the client, such as its computer operation system or a highly privileged application, since the client must discard the password after using it to obtain the access token.
OAuth grant provisioning UI
In the platform, the OAuth grant provisioning UI is the HTML page, used in Test Client, where the resource owner signs in and authorizes access, for the purposes of using Test Client.
The grant provisioning UI has the potential to include the logo for the application, pulled from the application information, and for the OAuth provider, as set up in the Branding tab in the OAuth Provider domain setup.
OAuth Provider
The platform's OAuth Provider add-on fulfils all aspects of the OAuth Authorization Server role.
OAuth refresh token
In OAuth 2.0, certain grant types support use of refresh tokens to facilitate longer access periods. This is useful in scenarios that extend over time, such as a regular monthly payment amount.
In OAuth 1.0a, once an access token is generated it is valid until revoked by the user. OAuth 1.0a does not support refresh tokens.
OAuth 2.0 introduces expiration of access tokens and adds a second type of token, a refresh token, that can be used in conjunction with the access token to allow users to give long-term permissions but yet maintain security. This process helps ensure that if a specific access token is compromised, a new one can be generated from the refresh token, which can be stored in the database on the server.
The access token grants immediate access but only for a limited time. The access token comes with two additional values: expires_in, which indicates the life of the access token, and refresh_token which can be used to get a new access token when the current token expires. Additional user approval is not needed, but the expiration and renewal add security to the process. When (or before) the access token expires, the refresh token can be used to generate a new access token.
OAuth resource owner
The end-user who is authorizing an application to access his/her resources for a specific purpose.
OAuth resource server
The server where the resources are stored. The resource server accepts requests and responds to approved requests using access tokens.
OAuth response_type parameter
Indicates instructions about the type of response expected for the OAuth/OpenID Connect message. This determines what parameters are returned from the endpoints used. See also OAuth Parameters.
OAuth scope
In the context of OAuth or OpenID Connect, a scope defines a set of one or more resources that the resource owner is granting access to. For a standard definition in the context of OpenID Connect, see http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint.
OAuth token endpoint
In OAuth 2.0, the token endpoint is the endpoint on the authorization server where the client app sends the authorization code, client ID, and client secret and receives in exchange an access token which allows the app to access the approved resources. For more information, see the OAuth 2.0 specification (external site).
OpenID
OpenID is an open standard for authenticating users. It can be used for access control and allows users to log on to different services with the same digital identity where these services trust the authentication body. OpenID simplifies the authentication process because there is only one username and password to remember. For more information, refer to the Site Admin help.
Since Google has now deprecated OpenID support and OpenID Connect is being adopted by the industry, it is better to switch to OpenID Connect.
OpenID Connect
An identity layer on top of the OAuth 2.0 protocol that allows the client to verify the identity of an end-user based on authentication by an authorization server. OpenID Connect was released in February 2014 and is gaining popularity. For example, Google is moving from OpenID to OpenID Connect for products such as the Google+ API, used by the platform's Google login domain. For more information, see Welcome to OpenID Connect (external site).

P

PingFederate
A federated identity management system based on the SAML protocol. PingFederate® supports SSO, SLO, and other federated identity standards. It can also be used as an OAuth 2.0 provider.
The platform supports PingFederate provider as a domain type (set up by the Site Admin).
PKCS12
A file format used for keystores. The private key and certificate can be stored in the same PKCS12 file. In the platform, this format is used for uploading the app keystore file in Test Client. The file extension can be p12 or pfx.
Postman
A free external Web client application used for testing APIs. See https://www.getpostman.com/postman.
promotion (from one environment to another)
Promotion is the process of propagating changes made in one Environment to another. The Promotion process is automated for efficiency and to help prevent mistakes that could occur in a manual process. Promotion is managed via the Promotion Coordinator.
Promotion requires installation and configuration of the Lifecycle Coordinator feature.
Promotion Coordinator
A Promotion Coordinator is a separate component that controls the promotion process and transfer of data between environments. There is a single Promotion Coordinator for all Environments.
proxy API
When you set up your API on the Akana API Platform and choose to use the Proxy feature, all traffic to your API endpoints is channeled via the platform. This offers significant benefits, including the ability to apply policies and monitor traffic at the proxy.
public key integration (PKI)
When a user registers an app in the Akana API Platform, the Shared Secret security option is the default. App owners who want to use Public Key Infrastructure (PKI) for secure message signing must specify Public Key Integration as the security option in the Akana API Platform user interface, on the App Details page.
To implement PKI, the app owner must get a public/private key pair, upload the public key to the Akana OAuth API verifies each incoming request using the public key.
public profile (app)
An app's Public Profile screen allows the app owner to brand the content of the OAuth Authorization screen. It is presented to external end-users of an app, and is used to grant an app rights to use an API. The OAuth Authorization screen applies to both Public and Private apps.

Q

QName
A unique identifier used for certain elements and attributes (Qualified Name). The APIs service uses QNames to identify elements such as API bindings and interfaces.
QNames are used to create a mapping between a URI and a namespace prefix.
QoS policy
Quality of Service policy. A QoS policy defines the level of service being offered to an app that is accessing an API; for example, the number of transactions per minute that are allowed for the app. In the platform, QoS policies are tied to license terms.

R

RAML
Acronym for RESTful API Modeling Language. RAML is a language based on YAML, and is used for describing RESTful APIs.
RDN
Acronym for Relative Distinguished Name—a unique identifier assigned to a platform member. In a non-federated scenario, the RDN is sufficient as a unique identifier for each member. See also FDN.
realm
A pattern that represents the part of URL-space for which an authentication request is valid. In OpenID or OpenID Connect, a realm is designed to give the end user an indication of the scope of the authentication request. The identity provider must present the realm when requesting the end-user's approval for an authentication request. The realm must be used by the identity provider to uniquely identify the relying party.
OAuth: The domain name for the OAuth provider. For more information, see http://tools.ietf.org/html/rfc2617#section-1.2.
refresh token
See OAuth refresh token.
registration code
A unique code generated and sent to a specific user in an email if the Site Admin adds the user (currently supported only via the API). The code is only valid for the account it is generated for, and expires after a pre-set period.
This is one of the several types of codes use to manage user signup and login.
relying party
In OpenID and OpenID Connect, the service provider is called the relying party. The relying party trusts the Connect provider to authenticate the user. In the context of the Akana API Platform, the platform is the service provider and the Site Admin sets up the Connect provider in Domains setup.
reset code
A unique code generated and sent to a specific user as a result of a password reset request. The code is only valid for the account that requested it, and expires after two days.
This is one of the several types of codes use to manage user signup and login.
resource (OAuth)
In the context of OAuth, a resource is something that the resource owner has full rights to, and can grant permission to, so that the application can perform some function on the resource, for the benefit of the resource owner. Examples: a Facebook calendar, a specific user's photo collection on a photo sharing website, a bank account..
restricted API access
Restricted access for an app means that the app's access to the API is restricted to a subset of the API, as defined by scope mapping, or to a specified, agreed-upon quota as defined by a QoS policy. Compare: unrestricted API access.
resource (platform)
In the Akana API Platform, a Resource is an item, such as an App or API, which has its own Board and set of activities. There are six resource types: API, app, business, contract, group, and user. In some instances, an app or API version is treated as a separate resource, since there might be multiple versions for a single app or API. In the platform API, scopes are also called Resources.
RSA
A popular and secure public key cryptography algorithm.
RSS
RSS is a widely used technology that allows users to subscribe to website content they're interested in. Once users subscribe to RSS feeds, updated content is automatically delivered to them in the form of an RSS channel, without the users having to check the individual websites for updates.
In the context of the Akana API Platform, many GET operations return the results in the format of an RSS channel.
RSS channel
The format in which information is conveyed using the RSS technology is called an RSS feed, web feed, RSS channel, or RSS document. It includes full or summarized text plus metadata (information about the text).
Many of the operations in the Akana OAuth API use RSS in the response. In general, GET methods that return any type of list return the information as an RSS channel, usually in either JSON or XML format as specified in the request message.

S

same-origin policy
Most browsers enforce the "same origin policy" security policy, which means that the parent window and an iframe can communicate only if they have the same domain name. It's a security measure to help prevent malicious activity.
SAML
Acronym for Security Assertion Markup Language. SAML is an identity federation standard that enables single sign-on. It is an XML-based standard for exchanging authentication and authorization data between a service provider (providing a service to the user) and an identity provider (providing user identity verification for the service provider).
One usage, in the context of the platform, is by OpenID Connect where it is used to provide single sign-on. The platform acts as the relying party.
SAML Artifact
A unique ID used by the service provider and identity provider to reference a specific user session or transaction. The SP can use the Artifact to query the IdP for information about the user.
SAML assertion
A SAML assertion is an XML document returned by the Identity Provider to the Service Provider after authentication of the user. The assertion has a very specific structure, as defined by the SAML standard. A SAML assertion has a {Subject} element which contains information about the user. It might have conditions and attributes associated with the information being conveyed. It is digitally signed and asserts that the user has been authenticated.
Note: the above definition applies to an authentication assertion, which applies in the context of the platform's support of SAML. There are other types of SAML assertions.
SAML Web SSO
Single sign-on over the Web using the SAML protocol.
scope
A scope value for an API version defines a subset of resources to which permission can be independently granted. In addition, the permission granted can be controlled by visibility (permission to view) or access (permission to send messages, to either the sandbox or production endpoint).
Defining scopes for an API allows the API administrator to control the granularity of API access granted to an app. When scopes are defined, app owners can request access to specific resources they want to access, and API owners can grant access to specific resources they want to share.
In the platform API, scopes are also called Resources. A ResourceID is a unique ID for a scope.
scope (OAuth)
For information on scopes in the context of OAuth, see OAuth scope.
Service Provider
In terms of SAML, the Service Provider (SP) offers a service to the user and allows the user to sign in by using SAML. When the user attempts to sign in, the SP sends a SAML authentication request to the Identity Provider (IdP). The IdP validates the request, authenticates the user, and creates a SAML assertion that represents the user's identity and, in some cases, sends additional information about the user in the form of associated attributes. The SAML assertion is digitally signed and encrypted and then sent back to the service provider that initiated the request.
Identity federation software at the SP receives the assertion, verified the authenticity, decrypts, and shares the information with the application.
SHA-1
SHA-1 is a cryptographic hash function, broadly used and trusted.
When you hash a value with SHA-1, the hash function returns a 160-bit string. This is the message digest. The value is hashed and sent with the message; at the receipt point, the value is hashed again, and the two hash values are compared. When the two hash values match, it is a secure, reliable indication that the message hasn't changed; the message at the receipt point is an accurate duplication of the message at the send point.
SHA-256
Part of the SHA-2 family of algorithms developed by the National Institute of Standards and Technology (NIST) and the National Security Agency (NSA) to succeed SHA-1. Each is named according to the number of bits in the output; so, whereas SHA-1 has 160 bits in the hash output, SHA-256 has 256.
shared secret
When you register your app, the AppID and Shared Secret are automatically generated. The Shared Secret is a binary hashed value, generated within the secure environment of the Akana API Platform. In the Security Credentials section of your app homepage you'll see that the Shared Secret option is the default security mechanism.
The Shared Secret approach follows the WS-Security digest authentication mechanism.
An authentication cookie used by CA SiteMinder.
soapUI
A free (or paid) application used for testing APIs. See https://www.soapui.org/.
SP
In SAML, abbreviation for Service Provider.
SSO
Acronym for single sign-on. SSO login allows a user to sign on to one software system using access credentials granted, and validated, by another system.
In the platform, an example of SSO login is the ability to sign on using Facebook or Google credentials. Note that whether an instance of the platform allows SSO login, and which providers are supported, is configurable, as determined by the Site Admin.
status
Individual resources have a status which might include such items as open connection requests, open trouble tickets, number of active consumers, number of active discussions, and number of unresolved alerts. Different resources have different status items.
Swagger
A third-party tool provided by the platform for automatic generation of API reference documentation. Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. It produces dynamically generated documentation from the information provided in the API definition. When a user defines an API, the structure is dynamically generated and added to a predefined Swagger template (resources.swg). The API Admin can then add title, description, implementation notes, and parameter information. The documentation displayed to the user is a blend of automatically generated content (Swagger resource file) and user-generated content (Swagger properties file).
Swagger properties file
Once the Swagger documentation is generated, the user can add comments and additional information. This information is stored in a Swagger properties file named {APIVersionID}.properties; for example, apiversion17171.acmepaymentscorp.properties. When a user views the API documentation in the platform, the user sees a merged combination of the automatically-generated Swagger resource documentation and the user-generated information stored in the Swagger properties file.
Swagger resource file
The automatically-generated API documentation file generated by Swagger based on the API definition. See Swagger.

T

target API
When defining an API on the platform, if an API is using the platform as a proxy, the TargetAPI is used to define the destination ("next-hop") endpoint for the API.
target URL
The URL for the target API. The target URL is the endpoint for the implementation; the destination ("next-hop") endpoint for the API.
tenant
An individual instance of the Community Manager developer portal. Each tenant generally has its own look and feel. A tenant will typically be a customer that is hosted within a shared system but wants to have some separation from other customers or tenants, while still being able to share information.
Test Client
The platform includes an API testing interface, Test Client, that acts as an easy-to-use testing tool for any API that is set up in the Community Manager developer portal. This test tool allows developers to thoroughly test all capabilities of the API.
It can be used for prototyping, testing, and troubleshooting apps against an API. It includes OAuth support for retrieving the OAuth token in order to process the message.
ticket
A type of feed entry, representing a trouble ticket created to raise an issue with a resource (app or API) or a connection. Tickets are typically created by a consumer of an API. Any member of the community can comment on a ticket, but it can only be marked as Resolved by the original creator or by an administrator of the target resource. For example, if Joe writes a ticket about an issue with the SkyBlue API, only Joe or the SkyBlue API Admin can mark the ticket as Resolved.
tModel
Abbreviation for Technical Model. A tModel is a data structure that resembles a type of XML web service. tModel is a core component of UDDI. A tModel represents a unique concept or construct, and is used to describe compliance with a specification, concept, category, identifier system, or shared design. Each tModel should include a URL to a document that describes the tModel in greater detail.
token
An access object sent to the requestor (client app) after authentication is complete and authorization has been granted. The token enables the client app to request access to the end-user's resources. OAuth, OpenID Connect, and SAML use tokens. There are different types of tokens, as defined in the applicable specification; for example, access tokens and bearer tokens.
token endpoint (OAuth)
See authorization token endpoint.
The token endpoint first authenticates the client application. It then allows the client application to send the code received from the authorization endpoint; in exchange, it generates an access token and sends it to the client application.
Users connect to the authorization endpoint; apps connect to the token endpoint.
transaction
In the context of the Akana OAuth API, a transaction is one instance of an app making a call to an API.

U

uddi
Acronym for Universal Description Discovery and Integration. UDDI is an open industry initiative sponsored by OASIS. It enables businesses to publish service listings and discover each other, and allows them to define how their services or software applications interact over the Internet.
uddi key
Each entity in a UDDI registry is assigned a key, which uniquely identifies that entity within the registry. Various parts of an API registered in the platform have unique UDDI keys assigned in Policy Manager; for example, the BindingKey and InterfaceKey.
unrestricted API access
Unrestricted API access for an app means that the contract is not limited to a specific license. The app has full access to all operations of the API. Compare: restricted API access.
user
A person with a registered login ID to the Akana API Platform. All users must complete the registration process so that the system can gather required information about them before granting access. Each user can choose to define a new username/password combination that will be managed within the Akana API Platform, or can leverage the integration of Akana API Platform with external security providers such as Facebook® for authentication. By completing the signup process, each individual is assigned the role of User; users can then assume other roles, such as API Administrator or App team member (depending on platform settings).
Note: To use the Akana API Platform API, users must sign up with the Akana API Platform rather than using a third-party authentication provider.
UserInfo Endpoint (OpenID Connect)
One of the two ways offered by the OpenID Connect specification for the app to learn information about the end user. The OpenID Connect Provider can publish a UserInfo endpoint, which is a protected resource that returns claims about the authenticated end-user.
The client sends a request to the UserInfo Endpoint using an access token. The UserInfo Endpoint returns the user info to the client app.
The OpenID Connect Provider can issue an ID Token (JWT token) from either the Authorization Endpoint or the Token Endpoint.
UTC
See Coordinated Universal Time (UTC).

V

version
Each app or API on the platform much have at least one version, and can have multiple versions. When a user creates an app or API on the platform, the first version is created automatically; when using the API it's important to complete both actions. If there is only one app or API version, deleting that version also deletes the app or API.
viewer
A Group that has a connection to a Private API. Members of the group have access to the Private API as long as the connection between the group and the API exists, and can see information about the Private API such as documentation and discussions. In future versions of the platform, the definition of Viewer might extend to individual users or businesses.

W

workflow
Workflow defines the sequence of steps that are followed in a business process, including such related data as conditions (for example, a ticket must be resolved before it can be closed), state (for example, a ticket can have states of Open, Resolved, and Closed), or role (for example, a certain step can only be completed by an Administrator).
Defining the workflow for a business process gives you control over the process and allows you to monitor and customize as needed to streamline the business process.
The platform includes default out-of-the-box workflows for certain resources, such as API contracts, and allows you to customize the workflow for several key resources.
workflow action
Certain types of activities on the platform must be done in a specific sequence. These are often managed by workflows. Each workflow action changes the state of the resource. Some examples of workflow actions are: requesting or approving an API contract, sending a group membership invitation, or changing the status of a ticket.
workflow definition key
A unique ID is assigned to each custom workflow when it's uploaded to the platform. Example: 2597f44e-8f1c-4cc4-8019-69781dd1a0d8. The workflow definition key indicates the custom workflow that's specified as the default for settings governing a certain type of resource, such as apps, APIs, or groups.
WWW-Authenticate response header
A standard HTTP response header used as part of the authentication process used in Akana OAuth API calls. When the server receives the request message, it challenges the client for valid authentication via the WWW-Authenticate response header. The client returns the authentication information in an Authorization header. The server validates the client information and then acts on the request message.

X

X-Forwarded-Host header
In OAuth Provider scenarios that include a reverse proxy, the outbound request to the OAuth Provider server must contain the X-Forwarded-Host request header, so that the server can identify the host value from the original request.
X-Forwarded-Proto header
In OAuth Provider scenarios that include a reverse proxy, the outbound request to the OAuth Provider server must contain the X-Forwarded-Proto request header, so that the server can identify the protocol from the original request.

Y

YAML
A data format. YAML 1.2 is a superset of JSON. YAML is not really a markup language since it is data-oriented rather than focusing on document markup. Whitespace indentation, rather than brackets, are used to denote structure. RAML, one of the API description document types supported by the API Platform, is based on YAML.

Z

zulu time
See Coordinated Universal Time (UTC).

Related Topics