Skip to content

Latest commit

 

History

History
530 lines (407 loc) · 17.2 KB

PublicApi.md

File metadata and controls

530 lines (407 loc) · 17.2 KB

PublicApi

All URIs are relative to http://localhost

Method HTTP request Description
disconnectUser GET /oauth2/sessions/logout OpenID Connect Front-Backchannel enabled Logout
discoverOpenIDConfiguration GET /.well-known/openid-configuration OpenID Connect Discovery
isInstanceReady GET /health/ready Check readiness status
oauth2Token POST /oauth2/token The OAuth 2.0 token endpoint
oauthAuth GET /oauth2/auth The OAuth 2.0 authorize endpoint
revokeOAuth2Token POST /oauth2/revoke Revoke OAuth2 tokens
userinfo GET /userinfo OpenID Connect Userinfo
wellKnown GET /.well-known/jwks.json JSON Web Keys Discovery

disconnectUser

disconnectUser()

OpenID Connect Front-Backchannel enabled Logout

This endpoint initiates and completes user logout at ORY Hydra and initiates OpenID Connect Front-/Back-channel logout: https://openid.net/specs/openid-connect-frontchannel-1_0.html https://openid.net/specs/openid-connect-backchannel-1_0.html

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");

    PublicApi apiInstance = new PublicApi(defaultClient);
    try {
      apiInstance.disconnectUser();
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#disconnectUser");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

This endpoint does not need any parameter.

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

HTTP response details

Status code Description Response headers
302 Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201. -

discoverOpenIDConfiguration

WellKnown discoverOpenIDConfiguration()

OpenID Connect Discovery

The well known endpoint an be used to retrieve information for OpenID Connect clients. We encourage you to not roll your own OpenID Connect client but to use an OpenID Connect client library instead. You can learn more on this flow at https://openid.net/specs/openid-connect-discovery-1_0.html . Popular libraries for OpenID Connect clients include oidc-client-js (JavaScript), go-oidc (Golang), and others. For a full list of clients go here: https://openid.net/developers/certified/

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");

    PublicApi apiInstance = new PublicApi(defaultClient);
    try {
      WellKnown result = apiInstance.discoverOpenIDConfiguration();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#discoverOpenIDConfiguration");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

This endpoint does not need any parameter.

Return type

WellKnown

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 wellKnown -
401 genericError -
500 genericError -

isInstanceReady

HealthStatus isInstanceReady()

Check readiness status

This endpoint returns a 200 status code when the HTTP server is up running and the environment dependencies (e.g. the database) are responsive as well. If the service supports TLS Edge Termination, this endpoint does not require the `X-Forwarded-Proto` header to be set. Be aware that if you are running multiple nodes of this service, the health status will never refer to the cluster state, only to a single instance.

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");

    PublicApi apiInstance = new PublicApi(defaultClient);
    try {
      HealthStatus result = apiInstance.isInstanceReady();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#isInstanceReady");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

This endpoint does not need any parameter.

Return type

HealthStatus

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 healthStatus -
503 healthNotReadyStatus -

oauth2Token

Oauth2TokenResponse oauth2Token(grantType, code, refreshToken, redirectUri, clientId)

The OAuth 2.0 token endpoint

The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" HTTP request entity-body. > Do not implement a client for this endpoint yourself. Use a library. There are many libraries > available for any programming language. You can find a list of libraries here: https://oauth.net/code/ > > Do note that Hydra SDK does not implement this endpoint properly. Use one of the libraries listed above!

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.auth.*;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");
    
    // Configure HTTP basic authorization: basic
    HttpBasicAuth basic = (HttpBasicAuth) defaultClient.getAuthentication("basic");
    basic.setUsername("YOUR USERNAME");
    basic.setPassword("YOUR PASSWORD");

    // Configure OAuth2 access token for authorization: oauth2
    OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
    oauth2.setAccessToken("YOUR ACCESS TOKEN");

    PublicApi apiInstance = new PublicApi(defaultClient);
    String grantType = "grantType_example"; // String | 
    String code = "code_example"; // String | 
    String refreshToken = "refreshToken_example"; // String | 
    String redirectUri = "redirectUri_example"; // String | 
    String clientId = "clientId_example"; // String | 
    try {
      Oauth2TokenResponse result = apiInstance.oauth2Token(grantType, code, refreshToken, redirectUri, clientId);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#oauth2Token");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

Name Type Description Notes
grantType String
code String [optional]
refreshToken String [optional]
redirectUri String [optional]
clientId String [optional]

Return type

Oauth2TokenResponse

Authorization

basic, oauth2

HTTP request headers

  • Content-Type: application/x-www-form-urlencoded
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 oauth2TokenResponse -
401 genericError -
500 genericError -

oauthAuth

oauthAuth()

The OAuth 2.0 authorize endpoint

This endpoint is not documented here because you should never use your own implementation to perform OAuth2 flows. OAuth2 is a very popular protocol and a library for your programming language will exists. To learn more about this flow please refer to the specification: https://tools.ietf.org/html/rfc6749

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");

    PublicApi apiInstance = new PublicApi(defaultClient);
    try {
      apiInstance.oauthAuth();
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#oauthAuth");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

This endpoint does not need any parameter.

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
302 Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201. -
401 genericError -
500 genericError -

revokeOAuth2Token

revokeOAuth2Token(token)

Revoke OAuth2 tokens

Revoking a token (both access and refresh) means that the tokens will be invalid. A revoked access token can no longer be used to make access requests, and a revoked refresh token can no longer be used to refresh an access token. Revoking a refresh token also invalidates the access token that was created with it. A token may only be revoked by the client the token was generated for.

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.auth.*;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");
    
    // Configure HTTP basic authorization: basic
    HttpBasicAuth basic = (HttpBasicAuth) defaultClient.getAuthentication("basic");
    basic.setUsername("YOUR USERNAME");
    basic.setPassword("YOUR PASSWORD");

    // Configure OAuth2 access token for authorization: oauth2
    OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
    oauth2.setAccessToken("YOUR ACCESS TOKEN");

    PublicApi apiInstance = new PublicApi(defaultClient);
    String token = "token_example"; // String | 
    try {
      apiInstance.revokeOAuth2Token(token);
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#revokeOAuth2Token");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

Name Type Description Notes
token String

Return type

null (empty response body)

Authorization

basic, oauth2

HTTP request headers

  • Content-Type: application/x-www-form-urlencoded
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201. -
401 genericError -
500 genericError -

userinfo

UserinfoResponse userinfo()

OpenID Connect Userinfo

This endpoint returns the payload of the ID Token, including the idTokenExtra values, of the provided OAuth 2.0 Access Token. For more information please refer to the spec.

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.auth.*;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");
    
    // Configure OAuth2 access token for authorization: oauth2
    OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
    oauth2.setAccessToken("YOUR ACCESS TOKEN");

    PublicApi apiInstance = new PublicApi(defaultClient);
    try {
      UserinfoResponse result = apiInstance.userinfo();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#userinfo");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

This endpoint does not need any parameter.

Return type

UserinfoResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 userinfoResponse -
401 genericError -
500 genericError -

wellKnown

JSONWebKeySet wellKnown()

JSON Web Keys Discovery

This endpoint returns JSON Web Keys to be used as public keys for verifying OpenID Connect ID Tokens and, if enabled, OAuth 2.0 JWT Access Tokens. This endpoint can be used with client libraries like node-jwks-rsa among others.

Example

// Import classes:
import sh.ory.hydra.ApiClient;
import sh.ory.hydra.ApiException;
import sh.ory.hydra.Configuration;
import sh.ory.hydra.models.*;
import sh.ory.hydra.api.PublicApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");

    PublicApi apiInstance = new PublicApi(defaultClient);
    try {
      JSONWebKeySet result = apiInstance.wellKnown();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling PublicApi#wellKnown");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

This endpoint does not need any parameter.

Return type

JSONWebKeySet

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 JSONWebKeySet -
500 genericError -