📘
TEOS User Guides
Contact CoreLedgerPrivacy Policy
TEOS API
TEOS API
  • 👋Welcome to TEOS API
  • Get started
  • TEOS API overview
    • Terms and concepts
      • Asset
      • Spark
      • Wallet
      • Supply
      • Warp
      • Invoice
      • Transaction
    • Architecture note
      • Tenant setup options
    • Authentication
    • Versioning
  • Using TEOS API
    • Postman examples
    • Rate limits
    • Dealing with blockchain transactions
      • How to get Ether for signing transactions
      • Transaction creation and submission
        • First transaction creation and submission for a new address on the private blockchain
    • Handling errors
      • 1xxxx codes
      • 2xxxx codes
      • 3xxxx codes
    • TEOS Events
    • Warp search
  • TEOS API references
    • TEOS API Swagger (OpenAPI)
  • Using additional APIs of TEOS Platform
    • User authentication flow with TEOS Authentication service and TMS
    • Device authorization flow with TxServer and TEOS Authentication service
    • Adding wallet to the TEOS Platform flow with TxServer and TEOS API
    • Using TxServer API
      • TxServer API (OpenAPI)
      • Key Pair Generation. Transaction Signing
      • Device Restoration
    • Using TEOS Authentication service
      • TEOS Authentication Service API
    • Using TMS API
      • TMS API Swagger (OpenAPI)
      • Handling errors
      • Changelog
    • Using Discovery Service
  • FAQ
  • Changelog
    • v0.9
    • Non-versioned changes
    • Previous versions (not supported)
  • Troubleshooting
Powered by GitBook
On this page
  • OAuth Endpoints
  • Discovery Endpoint
  • Authorize Endpoint
  • Token Endpoint
  • UserInfo Endpoint
  • Introspection Endpoint
  • Revocation Endpoint
  • End Session Endpoint
  • Specific endpoints
  • Rate limits

Was this helpful?

Edit on GitHub
  1. Using additional APIs of TEOS Platform

Using TEOS Authentication service

PreviousDevice RestorationNextUsing TMS API

Last updated 1 year ago

Was this helpful?

Additional APIs are required to be used along with TEOS API in case TEOS API Consumer doesn't have its own authentication service and needs TEOS Authentication service.

TEOS Authentication service (we also refer to it as AuthServer) is used to authenticate users for TEOS Platform components including TEOS API.

OAuth Endpoints

standard endpoint implementation details are described below. Custom endpoint references can be found .

Discovery Endpoint

Discovery Endpoint

GET /.well-known/openid-configuration

The discovery endpoint can be used to retrieve metadata about the AuthServer - it returns information like the issuer name, key material, supported scopes etc. See the for more details.

The discovery endpoint is available via /.well-known/openid-configuration relative to the base address, e.g.:

https://auth.coreledger.net/.well-known/openid-configuration

You can use the client library to programmatically access the discovery endpoint from .NET code. For more information check the IdentityModel .

Authorize Endpoint

Authorize Endpoint

GET /connect/authorize

The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user and optionally consent.

Query Parameters

Name
Type
Description

client_id*

identifier of the client

request

String

instead of providing all parameters as individual query string parameters, you can provide a subset or all of them as a JWT

request_uri

String

URL of a pre-packaged JWT containing request parameters

scope*

String

one or more registered scopes

redirect_uri*

String

must exactly match one of the allowed redirect URIs for that client

response_type

id_token requests an identity token (only identity scopes are allowed)

token requests an access token (only resource scopes are allowed)

id_token token requests an identity token and an access token

code requests an authorization code

code id_token requests an authorization code and identity token

code id_token token requests an authorization code, identity token and access token

response_mode

String

form_post sends the token response as a form post instead of a fragment encoded redirect

state

String

auth server will echo back the state value on the token response, this is for round tripping state between client and provider, correlating request and response and CSRF/replay protection. (recommended)

nonce

String

auth server will echo back the nonce value in the identity token (this is for replay protection)

Required for identity tokens via implicit grant.

prompt

String

none no UI will be shown during the request. If this is not possible (e.g. because the user has to sign in or consent) an error is returned

login the login UI will be shown, even if the user is already signed-in and has a valid session

code_challenge

String

sends the code challenge for PKCE

code_challenge_method

String

plain indicates that the challenge is using plain text (not recommended)

S256 indicates the challenge is hashed with SHA256

login_hint

String

can be used to pre-fill the username field on the login page

ui_locales

String

gives a hint about the desired display language of the login UI

max_age

String

if the user’s logon session exceeds the max age (in seconds), the login UI will be shown

acr_values

String

allows passing in additional authentication related information - identityserver special cases the following proprietary acr_values:

idp:name_of_idp bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)

tenant:name_of_tenant can be used to pass a tenant name to the login UI

Example:

GET /connect/authorize?
    client_id=client1&
    scope=openid email api1&
    response_type=id_token token&
    redirect_uri=https://myapp/callback&
    state=abc&
    nonce=xyz

(URL encoding removed, and line breaks added for readability)

Token Endpoint

Token Endpoint

POST /connect/token

The token endpoint can be used to programmatically request tokens. It supports the password, authorization_code, client_credentials, refresh_token and urn:ietf:params:oauth:grant-type:device_code grant types. Furthermore the token endpoint can be extended to support extension grant types.

Request Body

Name
Type
Description

client_id*

String

client identifier (required – Either in the body or as part of the authorization header.)

client_secret

String

client secret either in the post body, or as a basic authentication header

grant_type

String

authorization_code, client_credentials, password, refresh_token, urn:ietf:params:oauth:grant-type:device_code or custom.

scope

String

one or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued.

redirect_uri

String

required for the authorization_code grant type

code

String

the authorization code (required for authorization_code grant type)

code_verifier

String

PKCE proof key

username

String

resource owner username (required for password grant type)

password

String

resource owner password (required for password grant type)

acr_values

String

allows passing in additional authentication related information for the password grant type - identityserver special cases the following proprietary acr_values:

idp:name_of_idp bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)

tenant:name_of_tenant can be used to pass a tenant name to the token endpoint

refresh_token

String

the refresh token (required for refresh_token grant type)

device_code

String

the device code (required for urn:ietf:params:oauth:grant-type:device_code grant type)

Example:

POST /connect/token
CONTENT-TYPE application/x-www-form-urlencoded

    client_id=client1&
    client_secret=secret&
    grant_type=authorization_code&
    code=hdh922&
    redirect_uri=https://myapp.com/callback

In the case of wrong request it returns the problem

{
    "error": "invalid_client"
}

(Form-encoding removed and line breaks added for readability)

UserInfo Endpoint

UserInfo Endpoint

GET /connect/userinfo

The caller needs to send a valid access token representing the user. Depending on the granted scopes, the UserInfo endpoint will return the mapped claims (at least the openid scope is required).

Example:

GET /connect/userinfo
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json

{
    "sub": "248289761001",
    "name": "Bob Smith",
    "given_name": "Bob",
    "family_name": "Smith",
    "role": [
        "user",
        "admin"
    ]
}

Introspection Endpoint

Introspection Endpoint

POST /connect/introspect

It can be used to validate reference tokens (or JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries). The introspection endpoint requires authentication - since the client of an introspection endpoint is an API, you configure the secret on the ApiResource.

Example:

POST /connect/introspect
Authorization: Basic xxxyyy

token=<token>

A successful response will return a status code of 200 and either an active or inactive token:

{
    "active": true,
    "sub": "123"
}

Unknown or expired tokens will be marked as inactive:

{
    "active": false,
}

An invalid request will return a 400, an unauthorized request 401.

Revocation Endpoint

Revocation Endpoint

POST /connect/revocation

Request Body

Name
Type
Description

token*

String

the token to revoke

token_type_hint

String

either access_token or refresh_token

Example:

POST /connect/revocation HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

End Session Endpoint

End Session Endpoint

GET /connect/endsession

To use the end session endpoint a client application will redirect the user’s browser to the end session URL. All applications that the user has logged into via the browser during the user’s session can participate in the sign-out.

Query Parameters

Name
Type
Description

id_token_hint

String

When the user is redirected to the endpoint, they will be prompted if they really want to sign-out. This prompt can be bypassed by a client sending the original id_token received from authentication. This is passed as a query string parameter called id_token_hint.

post_logout_redirect_uri

String

If a valid id_token_hint is passed, then the client may also send a post_logout_redirect_uri parameter. This can be used to allow the user to redirect back to the client after sign-out. The value must match one of the client’s pre-configured PostLogoutRedirectUris.

state

String

If a valid post_logout_redirect_uri is passed, then the client may also send a state parameter. This will be returned back to the client as a query string parameter after the user redirects back to the client. This is typically used by clients to round-trip state across the redirect.

Example:

GET /connect/endsession?id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IjdlOGFkZmMzMjU1OTEyNzI0ZDY4NWZmYmIwOThjNDEyIiwidHlwIjoiSldUIn0.eyJuYmYiOjE0OTE3NjUzMjEsImV4cCI6MTQ5MTc2NTYyMSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo1MDAwIiwiYXVkIjoianNfb2lkYyIsIm5vbmNlIjoiYTQwNGFjN2NjYWEwNGFmNzkzNmJjYTkyNTJkYTRhODUiLCJpYXQiOjE0OTE3NjUzMjEsInNpZCI6IjI2YTYzNWVmOTQ2ZjRiZGU3ZWUzMzQ2ZjFmMWY1NTZjIiwic3ViIjoiODg0MjExMTMiLCJhdXRoX3RpbWUiOjE0OTE3NjUzMTksImlkcCI6ImxvY2FsIiwiYW1yIjpbInB3ZCJdfQ.STzOWoeVYMtZdRAeRT95cMYEmClixWkmGwVH2Yyiks9BETotbSZiSfgE5kRh72kghN78N3-RgCTUmM2edB3bZx4H5ut3wWsBnZtQ2JLfhTwJAjaLE9Ykt68ovNJySbm8hjZhHzPWKh55jzshivQvTX0GdtlbcDoEA1oNONxHkpDIcr3pRoGi6YveEAFsGOeSQwzT76aId-rAALhFPkyKnVc-uB8IHtGNSyRWLFhwVqAdS3fRNO7iIs5hYRxeFSU7a5ZuUqZ6RRi-bcDhI-djKO5uAwiyhfpbpYcaY_TxXWoCmq8N8uAw9zqFsQUwcXymfOAi2UF3eFZt02hBu-shKA&post_logout_redirect_uri=http%3A%2F%2Flocalhost%3A7017%2Findex.html

Specific endpoints

Rate limits

When developing integration with TEOS Authentication service you should take into account the limits described in Rate limits of TEOS API. Those limits are defined per tenant and shared by all TEOS Platform components.

If the error page is returned, it is always the same, and stating Sorry, there was an error: unauthorized_client Reason for such an error could be: ClientId, scopes or redirect_uri are sent to the /authorize endpoint not like they are defined in the . Exact reason could be determined by CoreLedger support.

AuthServer supports a subset of the OpenID Connect and OAuth 2.0 authorize request parameters. For a full list, see .

You can use the client library to programmatically create authorize requests .NET code. For more information check the IdentityModel .

AuthServer supports a subset of the OpenID Connect and OAuth 2.0 token request parameters. For a full list, see .

You can use the client library to programmatically access the token endpoint from .NET code. For more information check the IdentityModel .

The UserInfo endpoint can be used to retrieve identity information about a user (see ).

You can use the client library to programmatically access the userinfo endpoint from .NET code. For more information check the IdentityModel .

The introspection endpoint is an implementation of .

You can use the client library to programmatically access the introspection endpoint from .NET code. For more information check the IdentityModel .

This endpoint allows revoking access tokens (reference tokens only) and refresh token. It implements the token revocation specification .

You can use the client library to programmatically access the revocation endpoint from .NET code. For more information check the IdentityModel .

The URL for the end session endpoint is available via the .

The end session endpoint can be used to trigger single sign-out (see ).

You can use the client library to programmatically create end_session requests .NET code. For more information check the IdentityModel .

Refer to the

Discovery Service
here
IdentityModel
docs
here
IdentityModel
docs
spec
IdentityModel
docs
RFC 7662
IdentityModel
docs
(RFC 7009)
IdentityModel
docs
spec
IdentityModel
docs
Auth Server Swagger
discovery endpoint
OAuth 2.0
spec
IdentityModel
docs
here
Read more